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The PSCOPE-86 High-Level Program Debugger User’s Guide contains the following: 

• An introduction to the PSCOPE high-level program debugger. 

• An introductory PSCOPE debugging session. 

• A description of PSCOPE’s internal, screen-oriented editor. 

• Descriptions and examples of PSCOPE command language. 

• Instructions for loading and executing user programs. 

• An introduction to debug objects and symbols, as well as an explanation of 
the commands used to manipulate debug objects. 

• A description of PSCOPE utility commands. 

• PSCOPE error messages. 

• Instructions for configuring non-Intel terminals to use PSCOPE. 

• PSCOPE syntax. 

• PSCOPE reserved keywords. 


Manual Organization 

This manual contains 11 chapters and 9 appendixes, as follows: 

Chapter 1 defines PSCOPE and describes the program development process and 
the host system execution environment. Chapter 1 also details PSCOPE’s major 
functions and provides an introductory sample session. 

Chapter 2 explains how to invoke the debugger and discusses each of the invoca- 
tion controls. Chapter 2 also describes invocation error messages, how to enter 
commands from the keyboard, and PSCOPE’s internal editor. 

Chapter 3 describes PSCOPE command lines and is an overview of tokens, sym- 
bolic references, and symbol object types. Chapter 3 defines the operands and 
operators used in expressions and explains expression types, stepping, and the GO 
command. 

Chapter 4 details how to load programs and control execution using the GO 
command. 

Chapter 5 describes how to reference objects in a program and how to display and 
modify program objects. Additionally, Chapter 5 discusses fully qualified and par- 
tially qualified symbol references. 

Chapter 6 describes the four control constructs used by the PSCOPE command 
language: REPEAT, COUNT, IF, and DO. 
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Chapter 7 describes the command syntax necessary for defining, displaying, 
modifying, saving, and removing debug objects. 

Chapter 8 describes what debug procedures are and how to define, use, display, 
save, and remove them. 

Chapter 9 explains how to use code patches in a user’s program. 

Chapter 10 describes and explains the syntax for each of the utility commands and 
string functions available with PSCOPE. 

Chapter 1 1 describes how to use breakpoints and tracepoints to control and moni- 
tor program execution. 

Appendix A is a numerically ordered list of the PSCOPE error messages. 

Appendix B provides the codes necessary to configure PSCOPE to run on non- 
Intel terminals. 


Appendix C provides further information about using PSCOPE on the Series III 
development system. 

Appendix D provides further information about using PSCOPE on the Series IV 
development system. 

Appendix E contains the program upon which the examples in this manual are 
based. 
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Appendix G lists the PSCOPE reserved keywords. 

Appendix H lists PSCOPE commands and the pages on which they are discussed 
in this manual. 


Appendix I provides further information about using PSCOPE on the iRMX^^ 
operating system. 


Related Publications 

The following publications contain further information on the high-level languages 
PSCOPE supports: 

Pascal-86 User's Guide, order number 121539 

PL/M- 86 User's Guide for 8086- Based Development Systems, order number 
121636 " " ’ ’ 

FORTRAN-86 User's Guide, order number 121570 

The following publications contain further information on the Series III: 

Intellec ® Series III Microprocessor Development System Product Overview, order 
number 121575 

Intellec ® Series III Microprocessor Development System Console Operating 
Instructions, order number 121609 


VI 



PSCOPE-86 User’s Guide 


Preface 


Intellec ® Series III Microprocessor Development System Programmer's Reference 
Manual, order number 121618 

The following publications contain further information on the Series IV: 

Intellec ® Series IV Microcomupter Development System Overview, order number 
121752 

Intellec ® Series IV Operating and Programming Guide, order number 121753 
Intellec® Series IV ISIS- IV User^s Guide, order number 121880 


Notational Conventions 


This manual adheres to the following conventions when describing PSCOPE com- 
mand syntax. 


Convention 

Meaning 

UPPERCASE WORDS 

PSCOPE keywords. You must enter these words exact- 
ly as they appear, except that you can use either up- 
percase or lowercase. 

italics 

Grammar symbols for which you must substitute a 
value. These symbols are in italic face type. 

abc 

You must enter the symbols a, b, and c in exactly the 
order specified. 

Lab] 

The items between the brackets are optional. 

[abj* 

The items between the brackets are optional and may 
be repeated zero or more times. 

a|b 

Enter either the symbol a or the symbol b. 

a:: = be 

Replace the symbol a with the symbol b followed by c. 

punctuation 

You must enter punctuation other than ellipses (...), 
brackets ([ ]), and braces ({ }) entered as shown. For 
example, you must enter all the punctuation shown in 
the following command: 

SUBMIT PLM86(PROGA,SRC,'9 SEPT 810 

filename 

A filename is a valid name for the part of a pathname 
that names a file. 

pathname 

A pathname uniquely specifies a file and consists of a 
directory-name a filename. 

directory- name 

A directory- name \s that portion of a pathname which lo- 
cates the file by identifying the device and the directory 
containing the filename. 

system- id 

A system-id \s a generic label placed on sample listings 
where an operating system-dependent name would ac- 
tually be printed. 
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CNTL CNTL denotes the terminal’s control key. For 

example, CNTL-C means enter C while pressing the 
control key. 

apostrophe If your terminal has two apostrophe (or single quotes) 

symbols, determine which one PSCOPE accepts in 
command syntax. 
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CHAPTER 1 
INTRODUCTION 


This chapter introduces the high-level language debugger called PSCOPE-86. It 
contains an overview of PSCOPE-86 ’s capabilities and describes the preparation of 
a user program. 


WhatPSCOPEIs 

PSCOPE-86 is an interactive, symbolic debugger for object modules produced by 
the following compilers: 

Pascal-86 (version 2.0 or later) 

PL/M-86 (version 2.0 or later) 

FORTRAN-86 (version 2.0 or later) 

ASM-86 (version 2.0 or later) 

Both PSCOPE and the program being debugged reside in the microcomputer sys- 
tem’s memory (which is expandable to IM byte). PSCOPE runs under the ISIS 
operating system, the iNDX operating system, and the iRMX™-86 operating 
system (release 5 or later) . 


What PSCOPE Can Do 

With PSCOPE, you can examine and modify a program’s execution to find soft- 
ware logic errors. With PSCOPE commands, you can do the following: 

• Set breakpoints. 

• Single-step through high-level language statements, assembly language 
instructions, functions, or procedures. 

• Patch user code at either high-level language or assembly language level. 

• Display and modify program memory and 8086/8088 registers. When 
PSCOPE-86 runs under the iRMX-86 operating system, you can also display 
and modify 8087 registers. 

• Create and edit debug procedures, save these debug procedures, and recall 
them in future debug sessions. 

The Program Development Process 

PSCOPE is part of your microcomputer system’s development software. Figure 

1-1 shows how PSCOPE fits into a program development process. 

Typical program development consists of the following steps: 

1 . Write the source code with the host system editor. 

2. Compile the source code. This results in relocatable object code. 

3 . Correct any compile-time or assemble-time errors. Recompile or reassemble. 
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Figure 1-1 Generalized Program Development Process 


4. Link the object code file to selected library files with LINK86, using the 
BIND option. This creates a loadable version of the program. 

5. Execute, test, and debug the loadable object file using PSCOPE. 


Host System Execution Environment 

Appendixes B, C, D, and I contain information about the host system’s execution 
environment, including related manuals, required system hardware and software, 
maximum user program size, and host system resources used by the debugger 
(such as memory and open files) . 


Compiling or Assembling the Source Code 

When compiling or assembling the source code, include the following controls: 

1. The DEBUG control. This control instructs the compiler or assembler to 
place symbol information in the object file. 

2. The TYPE control. This control instructs the compiler or assembler to place 
type information in the object file. Symbol and type information is useful 
when debugging a user program with PSCOPE. 

3. With a compiler, the OPTIMIZE (0) control. This control instructs the 
compiler to turn off object code optimization. 
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Compiling Under the ISIS Operating System 

Assume that the source code file is called pager.src anA you are running on an In- 
tellec® Series III development system under the ISIS operating system. 


Invoking the Pascal Compiler 

Assume that the Pascal compiler is on disk drive one and that the source code is 
on disk drive zero. The following command will invoke the Pascal compiler. 

-run:f1 :pasc86 pager.src debug type optimize(O) 

Note that TYPE is a default option for the Pascal-86 compiler. 

Invoking the PL/M-86 Compiler 

Assume that the PL/M-86 compiler is on disk drive one and that the source code 
is on disk drive zero. The following command will invoke the PL/M-86 compiler. 

-run:f1 :plm86 pagersrc debug type optimize(O) 

Note that TYPE is a default option for the PL/M-86 compiler. 

Compiling Under the iRMX™-86 Operating System 

Assume that the source code file is called pager.src and that you are running on an 
86/3xx system under the iRMX-86 operating system. 

Choose either the COMPACT or the LARGE option. The iRMX-86 operating 
system does not support the SMALL or MEDIUM option. 


Invoking the Pascal Compiler 

Assume that the pathname of the Pascal compiler is /lang/pasc86 and that the 
pathname of the source code is /user/world/prog/pager.src. The following com- 
mand will invoke the Pascal compiler. 

-/Iang/pasc86 /user/world/prog/pager.src compact debug type 
optimize (0) 


Invoking the PL/M-86 Compiler 

Assume that the pathname of the PL/M-86 compiler is /lang/plm86 and that the 
pathname of the source code is /user/world/prog/pager.src. Here’s how to invoke 
the PL/M-86 compiler. 

-/Iang/pim86 /user/world/prog/pager.src. compact debug type 
optimize (0) 


Linking the Object Code 

PSCOPE does not support overlays. Do not link overlay files into the final debug 
load module. 
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Be sure to use the library files supplied with the operating system. The library files 
supplied with the ISIS operating system have the same names and perform the 
same functions as those supplied with the iRMX-86 operating system, but they 
differ internally. 

PSCOPE requires that the user program be in load-time-locatable (LTL) code. 
This means that code and data addresses are assigned by the system loader. Use 
the BIND control when invoking LINKS 6. 


Linking Under the ISIS Operating System 

Assume that the object code file is called pager.obj md you are running on an Intel- 
lec Series III development system under the ISIS operating system. Assume that 
LINK86 and the library files are on disk drive one and that pager, obj is on disk 
drive zero. 

When the program you plan to debug with PSCOPE-86 does real arithmetic, you 
have the choice of using the 8087 chip or the 8087 software emulator. 


Invoking the Linker for a Pascal Program 

The following command will invoke the linker for a Pascal program. 

run-:f1 :link86 pager.obj, :f1 :p86rn0.lib, & 

:f1 :p86rn1 .lib, & 

:f1 ;p86rn2.lib, & 

:f1 :p86rn3.lib, & 

:f1 :87null.iib, & 

:f1 :large.lib to pager.86 bind 

This example assumes that your microcomputer system does not contain the 8087 
chip. Because the Pascal example in this chapter does not do real arithmetic, 
e8087.1ib and e8087 are not required; 87null.lib is required to resolve external 
references in p86rn2.1ib and p86rn3.1ib. 

If your microcomputer system contains the 8087 chip, 8087. lib takes the place of 
e8087.1ib and e8087. 


Invoking the Linker for a PL/M-86 Program 

Here’s how to invoke the linker for a PL/M-86 program. 

-run:f1 :link86 pager.obj, :f1 :pim86.lib, & 

:f1 :compac.iib to pager.86 bind 

This example assumes that you chose the COMPAC option when compiling the 
PL/M-86 program. The default is SMALL. 


Linking Under the iRMX^”-86 Operating System 

Assume that you are running on an 86/3xx system under the iRMX-86 operating 
system. 

When running under the iRMX-86 operating system (release 5 or later) and 
invoking LINK86, include the following two options during the final link. 
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1. SEGSIZE(STACK(+2048)) This option increases the stack size by 

2048 bytes. 

2. MEMPOOL(+26000,0FF000H) LINK86 reserves 25000 bytes for 

dynamic memory allocation. 

When the program you plan to debug with PSCOPE-86 does real arithmetic, your 
microcomputer system must contain the 8087 chip. The iRMX-86 operating 
system does not support the 8087 software emulator. 

Invoking the Linker for a Pascai Program 

Assume that the pathname of link86 is /lang/link86 and that the pathname of the 
object file is /user/world/prog/pager.obj. The following command will invoke the 
linker for a Pascal program. 

•/Iang/link86 /user/world/prog/pagerobj, & 

/Iang/p86rn0.lib, & 

/Iang/p86rn1 .lib, & 

/Iang/p86rn2.lib, & 

/Iang/p86rn3.lib, & 

/iang/87null.lib, & 

/lang/large.iib to /user/worid/prog/pager.86 & 
segsize(stack(-l-2048)) mempool(-i-25000,0FF000H) 
bind 

If your program does real arithmetic, your microcomputer system must contain 
the 8087 chip, and you must link your program with 8087.1ib. Although the Pascal 
example in this chapter does not do real arithmetic, 87null.lib is required to 
resolve external references in p86rn2.1ib and p86rn3.1ib. 

Invoking the Linker for a PL/M-86 Program 

Assume that the pathname of link86 is /lang/link86 and that the pathname of the 
object file is /user/world/prog/pager.obj. The following command will invoke the 
linker for a PL/M-86 program. 

-/Iang/link86 /user/world/prog/pager.obj, & 

/Iang/plm86.lib, & 

/lang/compac.lib to /user/world/prog/pager.86 & 
segsize(stack(-l-2048)) mempool(+25000,0FF000H) 
bind 


Major Functions 

The following list briefly describes PSCOPE’s major functions and references the 
chapters containing more detailed information. 

• Internal editor (Chapter 2). The internal, screen-oriented editor lets you edit 
commands, debug procedures, and patches from the keyboard. 

• Single-stepping (Chapter 4). PSCOPE allows single-stepping through assem- 
bly language instructions, high-level language statements, and procedures. 

• Control blocks (Chapter 6) . You can use PSCOPE command language condi- 
tional and repetitive control constructs to build up blocks of debugger 
commands. 
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• Debug objects (Chapter 7). You can define and manipulate various types of 
debug objects, such as debug variables, debug procedures, and LITERAL- 
LYs (a form of command macro) . 

• Debug procedures (Chapter 8). You can define and edit debug procedures. 
Debug procedures consist of PSCOPE-86 commands. 

• Code patches (Chapter 9) . PSCOPE lets you add and delete code at the state- 
ment or instruction level without permanently changing your program. 
Patches made in PSCOPE are not permanent but they can be saved. Your 
program will not run with those patches outside of PSCOPE. If you load 
another program, PSCOPE deletes any previously defined patches. 

• Single-line assembler and disassembler (Chapter 9) . With these features you 
can modify and display assembly language instructions. 

• Utility commands (Chapter 10). With utility commands, you can perform 
such functions as obtaining on-line help, recording all or part of a debug ses- 
sion in a log file, and executing command files. 

• Breakpoints and tracepoints (Chapter 11). By setting breakpoints and 
tracepoints, you can control and monitor debugging. 


Introductory Sample Session 

This section contains two sample programs, one in Pascal-86 and one in PL/M-86. 
Both programs are called pager . and both perform the same function. 

The program reads text from a file called txtin, formats the text, and writes it to a 
file called txtout. The program inserts 10 spaces at the beginning of each line, thus 
creating a left margin, inserts page breaks, writes a heading for each page, and 
numbers the pages. The program may also double-space. 

A Debug Session With the Sampie Pascal Program 

Figure 1-2 is the list file for the sample Pascal program. 


SERIES-III Pascal-86, V3.0 
Source File: PAGER. SRC 
Object File: PAGER.OBJ 

Controls Specified: XREF, CODE, DEBUG, OPT!M!ZE(0), TYPE, 


STMT 

LINE 

NESTING 

SOURCE TEXT: PAGER.SRC 


1 

1 

0 

0 

program pager(input,output); 


2 

2 

0 

0 

const blank = ": 


3 

3 

0 

0 

var textin,textout 

:text; 

4 

4 

0 

0 

ch 

:char; 

5 

5 

0 

0 

leftmargin.i, linen umber 

:integer; 

6 

6 

0 

0 

linesend,pagenumber 

'.integer; 

7 

7 

0 

0 

double 

:boolean; 

8 

8 

0 

0 

procedure inlt{var leftmargin,linesend:integer; 

8 

9 

1 

0 

var double:boolean; 


var textin:text); 


(figure continues) 
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9 

12 

1 

0 

BEGIN 

9 

13 

1 

1 

leftmargin:==10; 

10 

14 

1 

1 

linesend: = 50; 

11 

15 

1 

1 

double: =false; 

12 

16 

1 

1 

writeln('leftinargin = Meftmargin:2); 

13 

17 

1 

1 

writein {'lines/page = ',linesend:2); 

14 

18 

1 

1 

writein ('double = '.double); 

16 

19 

1 

1 

writein 

END (*init*); 

16 

22 

0 

0 

Seject 


SERIES-111 Pascal-86, 


STMT LINE NESTING SOURCE TEXT: PAGER.SRC 


16 

24 

0 

1 

reset(textin,'txtin'); 

17 

25 

0 

1 

rewrite (textout.'txtout'); 

18 

26 

0 

1 

pagenumber; = 1; 

19 

27 

0 

1 

linenumber: = 1; 

20 

29 

0 

1 

initdeftmargin, linesend, double, textin); 

21 

31 

0 

1 

while eof (textin) =false do 

22 

32 

0 

1 

begin 

22 

33 

0 

2 

writein (textout); 

23 

34 

0 

2 

writein (textout); 

24 35 0 

',pagenumber:4); 

2 

writein (textout,' 

Intel Corporation 

25 

37 

0 

2 

writein (textout); 

26 

39 

0 

2 

repeat 

26 

40 

0 

3 

for i : = leftmargin down to 1 do 

27 

41 

0 

3 

write (textout, blank); 

28 

42 

0 

3 

while eoln (textin) =false do 

29 

43 

0 

3 

BEGIN 

29 

44 

0 

4 

read(textin,ch); 

30 

45 

0 

4 

write(textout,ch) 

END; 

32 

47 

0 

3 

If double=truethen 

33 

48 

0 

3 

BEGIN 

33 

49 

0 

4 

writein (textout); 

34 

50 

0 

4 

writein (textout); 

35 

51 

0 

4 

rmenumber: = linen umber + 2 
END 

36 

53 

0 

3 

else 

37 

54 

0 

3 

BEGIN 

37 

55 

0 

4 

writein (textout); 

38 

56 

0 

4 

rmenumber;=rmenumber+1 

END; 

40 

58 

0 

3 

read In (textin) 

until (linenumber=linesend) or (eof (textin) = true); 

42 

61 

0 

2 

page (textout) ; 

43 

62 

0 

2 

writein ('page = ',pagenumber:4); 

44 

63 

0 

2 

pagenumber: = pagenumber + 1; 

45 

64 

0 

2 

linenumber: = 1 
end; 

47 

66 

0 

1 

writein; 

48 

67 

0 

1 

writein ('end of file on textin encountered') 
END. (*main*) 


Figure 1-2 Listing of Pager in Pascal-86 


Introduction 
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The sample Pascal program has a bug in it. Statement #41 should read as follows: 
until (linenumber>linesend) or (eof(textin) ==true); 
rather than the following: 

until (linenumber=linesend) or (eof(textin) = true); 

The program works with the equal sign if you choose the single-space option. The 
loop does not terminate if you choose the double-space option and the program 
variable linesend is an even number. 

What follows is a sample debug session. The boxed text at the top explains the 
action of the PSCOPE dialogue following the boxed text. 

Invoke PSCdPE. Set up a list file called Load the program 

pager. 86. Define a debug variable called begin and set it equal to the current 
CS:IP, represented by a dollar sign ($) . , _ . - \ , . . 

; Define a debug procedure called again. This sets $ and namescope to begin. , 
This debug procedure is useful after you have executed your program once 
in PSCOPE and wish to execute again. . ' 

Define a debug procedure called fixUnenumber. This debug procedure checks 
if the program variable linenumberis greater than 50 and if so, sets it to 50. 

Define a break register called Une41. If you execute your program with this 
break register, execution stops at the end of the loop just before the terminat- 
ing check. If you now call the debug procedure fixUnenumber, the loop termi- 
nates as intended. 

Save the defined debug objects. Write them to the disk in a file called 
pager. mac. You can call up this file and use these debug objects in later debug 
session. ■. 


*list pager.log 

*load pager.86 
* 

^define pointer begin=$ 

^define proc again=do 
. «$=begin 
. «namescope=$ 

. «end 

♦ 

» define proc fixiinenumber = do 

■ «if linenumber >50 then 

■ • »linenumber=50 
■ . «end 

• *end 

^define brkreg Iine41 =#41 

:|C 

«put pager.mac debug 
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cur^ defin^. debug.object§:w the ptKxdj^S^A Also^^ 

*j ‘j^AiTOgram van^iesah^^ ,.;^V, 

j^^^^Iay.tii’&cuixeatvalbe’cifl^AM&'^'artihg'^^ '.f©V 

program executipnV& thaexeeutipli^^ifj^t^^ 

that, the program' itself; Writes itijliai variattfeS'to^ei'sfcrep^^ 

.g^^tputys.hpt mclndedih a hst file, Notice that the progr^^^a^able .^/fla^^ti 




«dir debug 
LINE41 . . brkreg 
BEGIN . . pointer 
FIXLNUMBERproc 
AGAIN . . proc 

«dir 

DIRof :PAGER 
PQ OUTPUT 

.. TEXT (file) 

pn IMDIIT 

1 >JC II >11 W 1 

.. TEXT (file) 

TEXTOUT 

.. TEXT (file) 

TEXTIN 

.. TEXT (file) 

CH 

. . char 

LINENUMBER 

. . integer 

1 

. . integer 

LEFTMARGIN 

. . integer 

PAGENUMBER 

. . integer 

LINESEND 

. . integer 

DOUBLE 

. . boolean 

INIT 

. . procedure 


LEFTMARGiN integer 

LINESEND integer 

DOUBLE boolean 

TEXTIN TEXT (file) 


*$ 

1C88H:0159H 
*go til #41 
leftmargin = 10 
lines/page = 50 
double = F 


[Break at #41] 

.the oirfeat value of. the prograra variabie //nenMtn^^ Ch^ it.tQ 

t ^ \ ; ' . ;■ : I ■; V'..'' ',l 

r Di^fcy, the address of lirtenumber. The period (.) signifies “the address j^S “; 
tlde|(fi]|?~ what syrnbolic variable is stored at that address ’w^th the 
: comin&d. The symbol rfs represents the data segment register.” 'V| .vj . 

. ' Display the data^sigment register. BecafiespT&eidefault faMx fe the 

. resulting number does not corresponBrt^ffiCthA ^ted|c^ -d|spl^^ 

. .linenuhiber was entered. Change the re- 

display the data segment registet Then returpTlieftjffp^ra&xloj^imal. 

Determine what prpgr|^jyplialfl,M“'tCte\'integei^^ 

memoiy template coihina^tQ.i.li^|iHihhet’^ the ad- 

dressof limnumbermiiMev^&fo^^il^Q^ 
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«linenumber 

+ 2 

*linenumber=3 

».linenumber 

1CC3H:0024H 

«eval ds:0024h symbol 
:PAGER.LINENUMBER 
* 

*ds 

7363 

*base=10h 

xds 

1CC3 

»base=10t 

* 

«dir integer 
DIRof :PAGER 
LINENUMBER 
I 

LEFTMARGIN 

PAGENUMBER 

LINESEND 

INIT.LEFTMARGIN 

INIT.LINESEND 

* 

^integer .linenumber 

1CC3H:0024H +3 

Display the value of double. Apply the BOOLEAN memory template com- 
mand to .double. Set double to true and again apply the BOOLEAN memory 
template command. 

Resume execution and break again at statement #41. Display the program 
variables linenumber md double. Display the break register You in- 

tended this break register to call the debug procedure flxlinenumber, but you 
neglected to include that call. 

« double 
FALSE 

« boolean .double 
1CC3H:002EH FALSE 
«double=true 
« boolean .double 
1CG3H:002EHTRUE 
# 

sgo til #41 
[Break at #41] 

« linenumber 

+5 

« double 
TRUE 
* 

»brkreg Iine41 

define brkreg LINE41 =#41 
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the break Hne41. Press the i key (for insert|S The menk pa the 

L Move the curm to the end of the 


the editor by bressing the q k^ (for quit)* The bi^u phanges to the 
■finhowini-' / . . > « - 'r*/ ’ ' ' ' ^ ' ' = ’ ’ - . ’ , W 


i^howixig: 

; r. idAbprt : Execute 


•jil^!Sf"&e e‘ keyj and.pSCXIPJl^'-,,;. 

it£&fe'esthebi:eakre^^i^2^i2>.v.t V/' •' ■•••;,; '"-r'' 


«edit Iine41 

define brkreg LINE41 =#41 

Block Delete Get Insert Quit View Xctiange 
define brkreg LINE41 =#41 

[insert] 

define brkreg LINE41 =#41 call fixiinenumber 
Abort Execute 


*define brkreg LINE41 =#41 call fixiinenumber 



»brkreg Iine41 

define brkreg LINE41 =#41 call fixiinenumber 
* 

«go using Hne41 

WARNING #51 4: Invalid return type from PROG called at breakpoint. [*] 
[Break at #41] 

#help e514 

E514 
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The debater procedure ‘called at, the break or trace point returned a value 
with an invalid type, or had no return value. The return value must be a 
BYTE, WORD, DWORD, BOOLEAN, or INTEGER (including 
' LONG/SHORT). A return value of TRUE is manufactured, causing theas- 
' sbciated break dr trace to be done. ~ ■; 

* 

«edit fixiinenumber 

»define proc FIXLNUMBER = do 

• «write 'linenumber= '.linenumber 

• «if linenumber >50 then 
. ■ «linenumber=50 

• • «write 'linenumber= linenumber 
• . » return true 

• • »else return false 
■ • »end 

. «end 

Resume execution. The GO comniand assumes the last go' specification. 
Typing GO is the same as typing GO USING tine41. The debug procedure 
fixiinenumber displays the line numbers as they increment. Notice linenumber 
go from 51 to 50. Then the break occurs. I i " • » ; ' ; • ■ 

Step through three high-level language statements. The program writes the 
program variable pagenumber to the screen. Because the program itself writes 
to the screen, this output does not appear in the list file. 

Step through one more statement. Display pagenumber and notice that it has 
incremented. Step through another statement and notice that the program 
has returned to the beginning of the loop, ready to take care of the second 
page. 


»go 


linenumber= 

4-9 

linenumber= 

-Ml 

linenumber= 

-1-13 

linenumber= 

-M5 

linenumber= 

-M7 

linenumber= 

-M9 

linenumber= 

-1-21 

linenumber= 

-t-23 

linenumber= 

■f25 

linenumber= 

4-27 

linenumber= 

4-29 

linenumber= 

+ 3^ 

iinenumber= 

4-33 

linenumber= 

4-35 

linenumber = 

+ 37 

linenumber= 

4-39 

linenumber= 

4-41 

linenumber= 

4-43 

linenumber= 

4-45 

linenumber= 

4-47 

linenurnber= 

4-49 

linenumber= 

4-51 

linenumber= 

4-50 

[Break at #41] 
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«lstep 

[Step at:PAGER#42] 
«lstep 

[Step at :PAGER#43] 

»lstep 

page = 1 

[Step at :PAGER#44] 
«lstep 

[Step at : PAGER #45] 

»pagenumber 

+ 2 

«lstep 

[Step at:PAGER#21] 



«go using Iine41 

linenumber= 

+3 

linenumber= 

+ 5 

linenumber= 

+ 7 

linenumber= 

-t-9 

linenumber= 

-Ml 

linenumber= 

-M3 

linenumber= 

-M5 

linenumber= 

-1-17 

linenumber= 

-M9 

llnenumber= 

-1-21 

linenumber= 

+ 23 

linenumber= 

-1-25 

linenumber= 

+ 27 

linenumber= 

+ 29 

linenumber= 

+ 3^ 

linenumber= 

-t-33 

linenumber= 

-1-35 

linenumber= 

+ 37 

linenumber= 

-1-39 

linenumber= 

H-41 

Mnenumber= 

-1-43 

linenumber= 

-f-45 

linenumber= 

-1-47 

linenumber= 

-1-49 

linenumber= 

-1-51 

linenumber= 

-F50 

[Break at #41] 


«lstep;lstep;lstep 

[Stepat;PAGER#42] 

[Step at;PAGER#43] 

page = 2 


[Stepat:PAGER#44] 

«lstep 


[Step at :PAGER#45] 

» integer .pagenumber 

1CC3H:002AH 

-1-3 


1-13 



Introduction 


PSCOPE-86 User’s Guide 


Resume execution using the break register Une41. The program encounters 
an end-of-file before /mewMOTterexceeds 50. - . ^ 

Close the list file. Exit PSCOPE. 

*go using Iine41 

linenumber= +3 
linenumber= +5 
linenumber= +7 
linenumber= +9 
linenumber= +11 
linenumber= +13 
linenumber= +15 
linenumber= +17 
linenumber= +19 
linenumber= +21 
page = 3 

end of file on textin encountered 

EXCEPTION: Program call to DQ$Exit 
[Stop at location 21 78H:0030H] 

»nolist 

«exit 

PSCOPE terminated 


A Debug Session with the Sampie PL/ M Program 

Figure 1-3 is the list file for the PL/M-86 program. 


SERIES-III PL/M-86 V2.3 COMPILATION OF MODULE PAGER 
OBJECT MODULE PLACED IN PAGER.OBJ 

COMPILER INVOKED BY: :F1 ;PLM86.86 PAGER.SRC OPTIMIZE(O) COMPACT DEBUG 
TYPE XREF CODE 


1 pager: 

do; 


2 1 

3 1 

4 1 

5 1 

6 1 

7 1 

8 1 
9 1 

10 1 
11 1 
12 1 
13 1 


declare connection 
declare (conin,conout) 
declare (bytes$read,err) 
declare compi 
declare boolean 
declare true 
declare false 
declare blank 
declare lfcr(2) 
declare ff 
declare (ch,i) 

declare (textin, textout) 
connection; 


literally 'word'; 
connection; 
word; 
word; 

literally 'byte'; 
literally 'Offh'; 
literally 'OOh'; 
byte data (32); 
byte data(10,13); 
bytedata(12); 
byte; 


14 1 declare (leftmargin,linesend,linenumber,pagenumber) word; 

15 1 declare double boolean; 


$eject 

/*The external procedure declarations follow.*/ 


(figure continues) 
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16 1 dqSattachprocedure (path$p,excep$p) connection external; 

17 2 declare path$p pointer, 

excepSp pointer; 

18 2 end; 

19 1 dqSdetacprocedure (conn, excepSp) external; 

h: 

20 2 declare conn connection, 

excepSp pointer; 

21 2 end; 

22 1 dq$creat procedure (path$p,excep$p) connection external; 

e: 

23 2 declare path$p pointer, 

excepSp pointer; 

24 2 end; 

25 1 dq$open: procedure (conn, access,num$buf,excep$p) external; 

26 2 declare conn connection, 

access byte, 

num$bufbyte, 
excep$p pointer; 

27 2 end; 

28 1 dq$close; procedure (conn,excep$p) external; 

29 2 declare conn connection, 

excep$p pointer; 

30 2 end; 

31 1 dqSread: procedure (conn, buf$p,count,excep$p) word external; 

32 2 declare conn connection, 

buf$p pointer, 

count word, 

excep$p pointer; 

33 2 end; 

34 1 dq$write: procedure (conn,buf$p,count,excep$p) external; 

35 2 declare conn connection, 

buf$p pointer, 

count word, 

excepSp pointer; 

36 2 end; 

37 1 dqSexIt: procedure (completion$code) external; 

38 2 declare completion$code word; 

39 2 end; 

$eject 

/*The local procedures follow.*/ 

40 1 numout: 

procedure (value,where); 

41 2 declare value word; 

42 2 declare where connection; 

43 2 declare digits(*) byte data('01 23456789'); 

44 2 declare chars (5) byte; 

45 2 declare I byte; 

46 2 doi = 1to5; 

47 3 chars(5-l)=digits (value mod 10); 

48 3 value= value/10; 

49 3 end; 

50 2 i=0; 

51 2 do while chars(i) = '0' and i<4; 

52 3 chars(i) = "; 

53 3 i = i + 1; 

54 3 end; 

55 2 call dq$write(where,@chars,5,@err); 

56 2 call dq$write(where,@lfcr,2,@err); 

57 2 end numout; 


(figure continues) 
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$eject 

/♦Now begins the executable code*/ 

58 1 leftmargin = 10; 

59 1 linesend = 50; 

60 1 double=true; 

/♦In the interest of space, initial variables are assigned in the code. A more useful program 
would read leftmargin, linesend, and double as input.*/ 


61 1 pagenumber = 1 : 

62 1 linenumber=1 : 

63 1 conout=dq$create(@(4,':CO;U@err); 

64 1 conin =dq$attach(@{4,':Cl:'),@err); 

65 1 call dq$open(conln, 1,0, @err); 

66 1 call dq$open(conout, 2,0, @err): 

67 1 call dq$write{conout,@ ('leftmargin = '),1 2, @err); 

68 1 call numout(leftmargin,conout): 

69 1 call dq$write(conout,@('lines/page= '),1 2,@err): 

70 1 call numout(linesend,conout); 

71 1 call dq$write{conout, ©('double = '), 12, @err); 

72 1 if double=true then 

73 1 do; 

74 2 call dq$write(conout,@('true'),5,@err); 

75 2 call dq$write(conout,@lfcr,2, ©err); 

76 2 end; 

77 1 else 

do; 

78 2 call dq$write(conout,@(' false'), 6, ©err); 

79 2 call dq$write(conout,@lfcr,2,@err); 

80 2 end; 


/♦Attach the file txtin and create the file txtout; open them.*/ 

81 1 textout=dq$create(@ (6, 'txtout'), ©err); 

82 1 textin=dq$attach(@(5, 'txtin'), ©err); 

83 1 call dq$open(textin, 1,0, ©err); 

84 1 call dq$open(textout, 2,2, ©err); 


$eject 

/♦Output to file textout.*/ 

85 1 bytes$read = 1; 

86 1 do while bytes$readOO; 

/♦Output the heading.*/ 

87 2 doi = 1to50; 

88 3 call dq$write(textout, ©blank, 1, ©err); 

89 3 end; 

90 2 call dq$write(textout,© ('Intel Corporation '), 21, ©err); 

91 2 call numout(pagenumber, textout); 

92 2 call dq$write(textout,@lfcr,2, ©err); 

93 2 call dq$write(textout,©lfcr,2,@err); 

/♦Output the page.*/ 

94 2 do while linenumber< =linesend and bytes$readO0; 

95 3 do 1 = 1 to leftmargin; 

96 4 call dq$write(textout, ©blank, 1, ©err); 

97 4 end; 

(figure continues) 
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98 3 bytes$read=dq$reacl(textin,@ch,1,@err); 

99 3 do whilech <> 13and bytesSread <>0; 

100 4 call dq$write(textout,@ch,1,@err); 

101 4 bytes$read=dq$read(textin,@ch,1 ,@err); 

102 4 end; 

103 3 bytes$read=dq$read(textin,@ch,1,@err); 

104 3 if double=truethen 

105 3 do; 

106 4 call dq$write(textout,@lfcr,2,@err); 

107 4 call dq$write(textout,@lfcr,2,@err); 

108 4 linenumber=linenumber+2; 

109 4 end; 

110 3 else 

do; 

111 4 call dq$write(textout,@lfcr,2,@err); 

112 4 linenumber=linenumber + 1 ; 

113 4 end; 

114 3 end; 

116 2 call dq$write{textout,@ff,1,@err); 

116 2 call dq$write(conout,@Cpage= 0,6, @err); 

117 2 call numout(pagenumber,conout); 

118 2 pagenumber=pagenumber+1; 

119 2 linenumber = 1 ; 

120 2 end; 

$eject 

/♦Close and detach files.*/ 

121 1 call dq$close(conln,@err); 

122 1 call dq$close(conout,@err); 

123 1 call dq$close(textln,@err); 

124 1 call dq$close(textout,@err); 

125 1 call dq$detach(conin,@err); 

126 1 call dq$detach(textin,@err); 

127 1 call dq$detach(textout,@err); 

128 1 halt; 

129 1 call dq$exit(compl); 

130 1 end; 


Figure 1-3 Listing of Pager in PL/M-86 


This program does not contain any obvious errors. In the interest of space, the 
code does not check the status returned after the file handling system calls. It is 
good programming practice to check this status and enter an error routine if the 
status is non-zero. 


Invoke PSCQPE, load the program pager. 86. Define a debug procedure 
called Inumber. This debug procedure is intended to be called by a trace 
register. It prints out the current line number and returns a value of true. 

Define a trace register called linellS. Statement #115 of the PL/M program 
writes a form feed at the end of a page in the file txtout. Printing out linenum- 
beraX this time displays its value when the loop is exited. 

Display the current value of CS:IP. 
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«load pager.86 
* 

^define proc LNUMBER =do 
■ «write 'linenumber= '.linenumber 
• « return true 
• »end 

^define trcreg LINE1 1 5 =#1 1 5 call Inumber 

1CC6H:0000H 


Begin execution with the trace register linellS. Exit FSC6PE. ‘ 


«go using Iine115 

leftmargin= 10 
lines/page= 50 
double= true 
linenumber— 51 
[At #115] 
page= 1 
linenumber= 51 
[At #11 5] 
page= 2 
linenumber= 23 
[At #11 5] 
page= 3 

EXCEPTION: Program cal! to DQSExit 
[Stop at location 1CC6HTo4AEHf 
»exit 

PSCOPE terminated 
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CHAPTER 2 
USING THE DEBUGGER 


This chapter describes how to use the debugger, including the following: 


• Invoking the debugger using initialization and configuration controls. 


• Entering commands from the keyboard. 


• Editing command lines with the line editor or the internal editor. 


• Using the menu commands. 


Invoking the Debugger 

Invoke the debugger by entering the following invocation line (notational conven- 
tions are defined in the Preface) : 

[RUN] Idirectory-name] PSCOPE [controls]* 

Where: 

direciory-name is the host system’s file path name. 

controls is any of the following invocation controls. The first con- 

trol listed in each pair is the default. The controls can be 
specified in any order. 

CRTiNOCRT 
MACRO I NOMACRO 
NOSUBMIT I SUBMIT 
VSTBUFFER {decimal- number) 

Each control is described in the following sections. 


The CRT | NOCRT Control 

CRT specifies a file which defines CRT characteristics that describe the control se- 
quences for communicating with the terminal. The form of this file is described in 
Appendix B. 

If you do not enter either CRT or NOCRT, the debugger looks for the CRT file 
PSCOPE.CRT in the same directory from which the debugger was invoked. If 
PSCOPE does not find the file PSCOPE.CRT, the debugger assumes that the key- 
board and CRT control sequences are the same as those on a standard Series III or 
Series IV development system. 

If you specify CRT without a file name, the default file (PSCOPE.CRT) must 
exist; otherwise, PSCOPE displays an error message. 
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If you specify NOCRT, the debugger does not look for a CRT file. It assumes a 
Series III- or Series IV-based machine. 

If you rename the debugger file and invoke it with the new name, the debugger 
looks for a CRT file with the new name. 


Syntax 

CRT [{filename)] 

NOCRT 

Abbreviation 

CR|NOCR 

Default 

PSCOPE.CRT 

Example 

Following are some examples of the CR.T |NOCR.T control commands. 

RUN PSCOPE 

run pscope crt(1510t.crt) 

RUN PSCOPE NOCRT 


The MACRO | NOMACRO Control 

MACRO specifies a file containing debugger commands to be executed during 
debugger initialization. You create MACRO files containing command definitions 
useful to a particular application, such as abbreviations or debugger procedures 
which will be used over several debug sessions. 

If you do not enter either MACRO or NOMACRO, the debugger looks for the file 
PSCOPE. MAC in the same directory from which the debugger was invoked. 

The PSCOPE. MAC file can contain any number of debugger commands to be ex- 
ecuted on initialization. For example, the MAC file can automatically define 
abbreviations using the LITERALLY command (discussed in Chapter 7). 

If you specify MACRO without a file name, the default macro file must already 
exist. 

If you specify NOMACRO, the debugger does not look for a macro file. 

If you rename the debugger and invoke it with the new name, the debugger auto- 
matically looks for a MAC file with the new name. 

A macro file is not required. 
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Syntax 

MACRO l(filename)] 

NOMACRO 

Abbreviation 

mrInomr 

Default 

PSCOPE.MAC 

Example 

Here are some sample MACRO ] NOMACRO control commands. 

run pscope macro (procs.mac) 

RUNPSCOPENOMR 

The NOSUBMIT I SUBMIT Control 

SUBMIT indicates that PSCOPE is to operate inside of a SUBMIT file. If you speci- 
fy SUBMIT, you must use the standard system line editor rather than PSCOPE’s 
extended line editor. Using the standard system line editor ensures that SUBMIT 
file commands are echoed properly to the system terminal. 


Syntax 

NOSUBMIT 

SUBMIT 

Abbreviation 

NOSMiSM 

Default 

NOSUBMIT 

Example 

The following illustrates how to use the NOSUBMIT | SUBMIT control. 

run pscope sm 
RUN PSCOPE NOSM 
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The VSTBUFFER Control 

PSCOPE employs a virtual symbol table. Only a portion of the user-program 
symbol table need reside in physical memory at any one time. The entire symbol 
table resides on disk. 

VSTBUFFER specifies the amount of physical memory to be used for the virtual 
symbol table. Replace decimal-number mih the number of kilobytes that you want 
reserved for the virtual symbol table buffer. The parameter decimal-number must 
be a number in the range 5 through 61 . 

The larger the virtual symbol table buffer is, the less time PSCOPE must spend 
manipulating the symbol table. On the other hand, a small virtual symbol table 
buffer frees up more memory for use by the user program and debug objects. 


Syntax 

VSTBUFFER(dec/ma/-number) 

Where: 

decimal-number is a number in the range 5 through 61, specifying the 
amount of physical memory in kilobytes to be used for 
the virtual symbol table. 


Abbreviation 

VSTB(decimal-numbei) 

Default 

VSTB(5) 

Invocation Error Messages 

You can make three types of errors when entering the invocation line: 

• An unrecognized control 

• A control missing a required parameter 

• A control with an invalid parameter 

When an invocation error occurs, PSCOPE displays an error message, followed by 
the operating system prompt. You can then enter a corrected invocation line. 

PSCOPE displays the following error message when you enter an unrecognized 
control character: 

UNKNOWN CONTROL: control 
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PSCOPE displays the following error message when you do not include the re- 
quired parameter with the invocation line; 

PSCOPE OPTION ERROR 
OPTION; control 
ERROR: message 
PSCOPE terminated 

PSCOPE displays the following error message when you enter an invalid 
parameter: 

PSCOPE I/O ERROR 
F\LE:file-type 
NAME:filename 
ERROR.message 
PSCOPE terminated 

Where: 

file-type is CRT or MAC. 

filename is the name of your file. 

message is the error message that identifies the problem. 


Using the Debugger 

After you correctly enter the invocation line, the debugger clears the screen and 
displays the following sign-on message: 

system-id PSCOPE-86, Vx.y 

The system- id idtuiiries the host system. On the Series III, the host system-id is 
SERIES III. 

In Vx.y xis the debugger version number, and y is the change number. After sign- 
ing on, the debugger prompts for commands with an asterisk (*). User software 
can then be loaded, executed, tested, and debugged by entering the commands de- 
scribed in subsequent chapters. After completing an operation in response to a 
command, the debugger prompts for new input. 


You can perform any of the following operations when the debugger prompt is 
displayed: 

• Enter a command from the keyboard. 

• Enter commands from an external file. 

• Re-execute the last command (CNTL-E) . 

• Enter the internal editor to create debug objects or edit commands. 

• Suspend or cancel debugger terminal output. 

While the debugger is executing, you can interrupt operation as follows: 

• Suspend terminal output by entering CNTL-S and resume terminal output 
by entering CNTL-Q. 
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• Cancel the command in progress by entering CNTL-C. 

You can create a file containing debugger commands, then use the INCLUDE 
command described in Chapter 10, to enter the commands from that file. 

You can record the debugging session by using the LIST command (described in 
Chapter lOT The LIST command sends all debugger terminal output to the speci- 
fied file, either on disk or hard copy. The file includes PSCOPE prompts, user 
input lines, PSCOPE output, and error messages. It does not, however, contain 
output from the program being debugged. 


Terminating a Session 

Enter the following EXIT command to exit the debugger; 

EXIT 

The debugger responds with the following message; 

PSCOPE terminated 

The debugger closes all open files and returns to the operating system. 


Command Entry 

The debugger prompt (*) indicates that the system is in command-entry mode. In 
this mode, the debugger places characters entered at the terminal in a command 
buffer until the end of a complete command coincides with the end of a command 
line. At this point, the debugger executes all commands in the buffer in the order 
in which they were read. (Legal command line length is virtually unlimited, 
depending on the amount of workspace available.) 

You can continue commands which will not fit on one line on subsequent lines. 
The continuation flag, an ampersand (&) at the end of the line to be continued, is 
optional because the debugger can recognize the end of a completed command in 
most cases. (PSCOPE issues a double asterisk (**) prompt if it needs more com- 
mand input.) The exception is when a command has an optional parameter that is 
placed on the next line. In this case, the debugger executes the partial command 
(since it is complete) unless you include the continuation flag. 

Continuation flags let you specify a multi-line sequence of commands before they 
are executed (without using the DO construct explained in Chapter 6). 

You must separate commands with a semicolon when you specify more than one 
command on a line. 


Line-Editing Keys 

You can edit command input in line-oriented mode using the following line editing 
functions: 

RUBOUT key Deletes the character to the left of the cursor. 
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CNTL-F 

or Deletes the character at the cursor. 

DEL CHAR 

(RUB OUT) 

CNTL-X Deletes all characters to the left of the cursor. 

CNTL-A Deletes the character at the cursor and all characters to the 

right of the cursor. 

CNTL-Z 

or Deletes the entire current line. 

CLEAR LINE 

Left Arrow key Moves the cursor one character to the left. 

Right Arrow key Moves the cursor one character to the right. 

HOME key Operates with the left or right arrow key. Moves the cursor 
to the beginning of the line if pressed after the left arrow 
key. Moves the cursor to the end of the line if pressed 
after the right arrow key. 

CNTL-C Cancels the command in progress. 

ESC key Enters PSCOPE’s internal editor. 


Syntax Errors 

A syntax error is an error in the command’s format. When the debugger finds a 
syntax error, it displays the following message: 

(Syntax error 

The arrow ( t ) is aligned under the portion of the command line containing the 
error. If the error is located near the right edge of the screen, the message takes 
the following form: 

Syntax error | 

You can correct commands in which errors were detected by pressing ESC to 
invoke the internal editor and using the appropriate editor commands. You can 
then execute the corrected command after exiting from the editor. 

The Internal Screen-Oriented Editor 

PSCOPE contains a built-in editor for modifying debug procedures, 
LITERALLYs, patches, debug registers, the most recent command, and the most 
recent GO command. For example, use the editor to modify the specification of a 
break register. 

The edit- item may be the name of a debug procedure, the name of a debug register, 
the name of a LITERALLY definition, the keyword PATCH followed by the 
patch’s starting address, or the keyword GO (for editing the current GO 
specification) . 

Without an argument, the EDIT command is invoked with an empty buffer. Press- 
ing the ESC key invokes the editor with the last command as the edit item. 
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The internal editor is screen-oriented. Figure 2-1 shows a typical menu. If you do 
not have an Intel terminal, you must include a CRT configuration file when you 
invoke PSCOPE. This file (called PSCOPE.CRT) contains the I/O sequences for 
cursor control. You can also use this file to reprogram special keys such as the di- 
rection arrows, ESC, and HOME keys to map their functions to other keys. 

Because the internal editor is interactive and screen-oriented, you cannot use it if 
you specified the SUBMIT control when you invoked PSCOPE. Nor can you use 
the VIEW command when PSCOPE is running under SUBMIT. 


Entering the Internal Editor 

You can invoke the internal editor in the following two ways: 

• By pressing the ESC key either at the debugger prompt or during command 
entry. 

If you press ESC immediately after the debugger prompt, the last command 
is recalled for editing. 

If you press ESC during command entry, you can edit the entire command 
being entered. 

• By entering the EDIT command immediately after the debugger prompt. 


Syntax 

EDIT [edit-item] 

Where: 

edit-item is one of the following: 

debug-symbol is the name of an existing debug object of one of the 
debug types (not memory or user types) specified in 
Table 3-5. If you specified debug-symbol, its defini- 
tion (the command that defined the debug object) is 
brought up for editing. 

PATCH address 

GO 

If you specify PATCH, the corresponding debugger program PATCH is made 
available for editing. 

If you specify GO, the text of the last GO command is brought up for editing. 

If you do not specify anything, the editor invokes with an empty edit space. 


Exiting the Internal Editor 

After exiting the internal editor (using the QUIT command) , you can either exe- 
cute or ignore the command(s) you just edited. 
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Internal Editor Display 

As shown in Figure 2-1, the internal editor uses the screen’s two bottom lines for 
the edit message line and the menu option line. The remainder of the screen is the 
edit display area. 



1372 


Figure 2-1 Editor Display 


The internal editor displays a maximum of 79 columns of text but supports longer 
lines. For lines exceeding 79 characters, an exclamation point (!) is displayed as 
the last character to indicate that more text exists beyond the end of the display. 
When you move the cursor logically beyond the display, it remains physically in 
the right-most position in the line. All edit functions can act on text existing 
beyond the display area, but the display is not affected. 

The internal editor displays the printable ASCII characters (20h to 7Eh). It dis- 
plays unprintable characters as question marks (?). The internal editor considers 
the carriage return (CR) and the linefeed (LF) characters printable characters. 
The CR/LF combination acts as a single character called return. A tab is interpret- 
ed as four spaces. 


Internal Editor Commands 

The internal editor uses the cursor control keys and editor display options for com- 
mand input. 

Cursor Control Keys. The following cursor control keys control movement 
within the text being edited: 

• Up arrow 

• Down arrow 

• Left arrow 

• Right arrow 

• HOME 

• RETURN 
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The cursor control keys operate as described in the following sections. 


Up Arrow Key. Pressing the up arrow key moves the cursor up one line from its 
current column position. If the cursor is already in the top line of the screen, press- 
ing the up arrow key moves the cursor to the preceding line and displays the text 
with that line positioned six lines from the top of the screen (standard Intel 
terminals) . The up arrow has no effect if the cursor is on the first line of the text 
being edited. 


Down Arrow Key. Pressing the down arrow key moves the cursor one line down 
from its current column position. If the cursor is already in the last line on the 
screen, the text scrolls up one line. The down arrow key has no effect if the cursor 
is in the last line of text. 


Left Arrow Key. Pressing the left arrow key moves the cursor one character to 
the left. If the cursor is at the beginning of a line, the cursor moves to the carriage 
return at the end of the preceding line. If the cursor is at the beginning of the 
screen, pressing the left arrow key moves the cursor to the end of the preceding 
line and displays the text with that line positioned six lines from the top of the 
screen (standard Intel terminals). The left arrow key has no effect if the cursor is 
at the beginning of the text. 


Right Arrow Key. Pressing the right arrow key moves the cursor one character to 
the right. If the cursor is at the last character of the last line on the screen, the 
screen scrolls up one line. The right arrow key has no effect if the cursor is at the 
end of the text. 


HOME Key. The HOME key is used with the directional cursor keys, as follows: 

• Pressing HOME after pressing an up or down arrow key displays the previous 
or next screen of text, respectively. The cursor remains in the same relative 
location on the new page. 

• Pressing HOME after pressing a left or right arrow key moves the cursor to 
the beginning or end of the line, respectively. 

You can press HOME any number of times after pressing a directional key. 


RETURN Key. Pressing the RETURN key when the editor is expecting a com- 
mand moves the cursor to the beginning of the next line of text. If the cursor is in 
the last line of the text display area, the text is scrolled up one line. If the cursor is 
at the end of the text, pressing the RETURN key has no effect. 


Delete Keys. You can use the following delete keys when the editor is at the com- 
mand level or in the insert or exchange mode: 

• RUBOUT key 

Deletes the character to the left of the cursor. 

• CNTL-F 

Deletes the character at the cursor. 
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• CHAR DEL 

Deletes the character at the cursor. 

• CNTL-X 

Deletes all characters to the left of the cursor. 

• CNTL-A 

Deletes the character at the cursor and all characters to the right of the 
cursor. 

• CNTL-Z 

Deletes the current line. 

• CLEAR LINE 
Deletes the current line. 


Menu Commands 

The menu command provides the following command options: 

• Block 

• Delete 

• Get 

• Insert 

• Quit 

• View 

• Xchange 


To select each menu command, enter the first letter of the command (either 
lowercase or uppercase) . The editor beeps if you give it an unexpected command 
character. 

Enter CNTL-C to abort the menu command in progress. The editor ignores the 
CNTL-C if it is waiting for a command. 

The menu always indicates which options are available. Some menu commands 
lead to sub-menus (for example. Quit and Block) . 


BLOCK Command (B) 

The BLOCK command lets you mark off a block of text and place it in the block 
buffer for later retrieval (with the GET command) . 

To place text into the buffer, move the cursor to the first character in the block of 
text desired and press B. The editor displays the following sub-menu; 

Buffer Delete 
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Move the cursor just beyond the character at the end of the block to be delimited 
and again enter B. (The beginning and ending characters of the block being 
delimited are marked with an at sign ( @) .) The text is now in the buffer. 

Use the left, right, up and down arrow keys and the HOME and RETURN keys to 
move the cursor to the end of the block. 

Note that the block buffer holds only one block of text. If you execute a block or 
delete command before retrieving the contents of the block buffer with the GET 
command, the original contents are overwritten by the new block of text. 


DELETE Command (D) 

The DELETE command lets you mark off a block of text, place it in the block 
buffer for later retrieval (with the GET command) , and then delete it. 

To place text in the buffer, move the cursor to the first character in the block of 
text desired and press D. The editor displays the following sub-menu: 

Buffer Delete 


Move the cursor just beyond the character at the end of the block to be delimited 
and again enter D. (The beginning and ending characters of the block being 
delimited are marked with an at sign (@).) 

Use the left-, right, up and down arrow keys and the HOME and RETURN keys to 
move the cursor to the end of the block. 

Note that the block buffer holds only one block of text. If you execute a block or 
delete command before retrieving the contents of the block buffer with the GET 
command, the original contents are overwritten by the new block of text. 


GET Command (G) 

The GET command retrieves the contents of the block buffer (see the block and 
delete commands) and inserts it at the current cursor location. The block buffer is 
initially the null string. 

You can move text from one part of the file to another by doing one of the 
following: 

• Placing the text to be inserted in the block buffer with the delete command. 

• Moving the cursor (with the cursor control keys) to where you want the text 
inserted. 

• Entering the GET command. 


INSERT Command (I) 

The INSERT command puts the editor into insert mode, which is indicated by 
[insert] on the menu line. Each character you enter is then inserted at the cursor 
until you press ESC. The display echoes the new text as you insert each character. 
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In insert mode, you can use the cursor control keys (left, right, up and down 
arrow, HOME and RETURN) and the delete keys. Pressing RETURN after insert- 
ing text in the last line scrolls the text up one line. 

If the cursor is positioned beyond the end of a line when entering text in insert 
mode, the cursor moves to the point immediately before the end (or carriage 
return) of the current line, and the insertion begins beyond the line. 


QUIT Command (Q) 

The QUIT command lets you exit the editor and either pass or not pass a command 
back to the debugger. The editor displays the following sub-menu when you enter 

Q: 


Abort Execute 

Enter A (abort) to exit the editor without passing a command back to the 
debugger. 

Enter E (execute) to exit the editor and process the edited text as a command. 


VIEW Command (V) 

The VIEW command redisplays the screen with the line containing the cursor 
positioned in the middle of the screen, unless centering places the beginning of 
the text below the top of the screen. 


XCHANGE Command (X) 

The XCHANGE command puts the editor into exchange mode, indicated by 
[exchange] on the menu line. The XCHANGE command lets you replace the char- 
acter at the cursor, one for one. The cursor moves one character to the right each 
time you replace a character. 

Press ESC to end the exchange mode. 

While in exchange mode, you can use any of the cursor control keys to move the 
cursor. Characters you enter beyond the end of a line are inserted before the 
RETURN in that line. 


The VIEW Command 

The VIEW command allows you to examine files without exiting PSCOPE. This is 
a PSCOPE command; it is distinct from the view command that belongs to the 
PSCOPE internal editor. 


Syntax 

VIEW pathname 
Where: 

pathname is the fully-qualified name of the text file you want to examine. 
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Description 

The VIEW command is menu driven. After you issue the command, the first 23 
lines of the specified file appear on the screen. The last two lines of the screen con- 
tain the VIEW menu as shown in the following example: 


VIEW :f1 :pager.src 

Again Find -find Jump Quit Roll Set View 


Choose a menu item by entering its first letter (VIEW is not case-sensitive). For 
example, entering Q chooses Quit, which terminates the VIEW command and re- 
turns you to the PSCOPE prompt. 

Again Repeats the last command option. For example, if you just 

searched for the text string “reset”, entering A searches for the 
next occurrence of that text string. 

Find Searches for a text string in the forward direction. After you enter 

the F, VIEW requests a text string. Enter the text string and termi- 
nate it with an ESC. Find remembers the specified text string. If 
you enter another F, you can search for the next occurrence of the 
string by just entering an ESC. 

-find Searches for a text string in the reverse direction. After you enter 

the hyphen (-) , VIEW requests a text string. Enter the text string 
and terminate it with an ESC. 

Jump Moves the cursor to the start or the end of the file. After you enter 

the J, VIEW presents the following new menu: 


Start End 

Choose S for the start of the file and E for the end of the file. 

Quit Returns you to the PSCOPE prompt. 

Roll Moves the cursor to the last line on the screen, then moves the 

screen down through the file one line at a time. You can stop rolling 
with CNTL-S and resume rolling with CNTL-Q. Terminate the roll 
with an ESC. 

Set Determines the way VIEW displays the file. After you enter the S, 

VIEW presents the following new menu: 

Leftcol Tabs Viewrow 

Choose one item by entering its first letter. 

Leftcol is zero by default; zero identifies the first column. You can 
change the first column displayed on the screen. This is useful 
when your file contains rows longer than the screen display. When 
leftcol is other than zero, column zero contains an exclamation 
point (!). 
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Tab is four spaces by default. You can alter the tab settings in your 
file display. This alteration is only for the display. Your file is not 
edited. 

Viewrow is line five by default. The rows on the screen are labeled 
0 through 22. Setting viewrow to a row number moves the row the 
cursor is on to that row number. 
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CHAPTER 3 
COMMAND LANGUAGE AND 

EXPRESSIONS 


This chapter describes PSCOPE command line format. It gives an overview of 
tokens and symbol object types. It defines the operands and operators you can use 
in expressions and explains the rules for combining different expression types. 


Tokens 

Tokens are the smallest meaningful units in a command line. Each token belongs 
to one of the following classes; 

• Delimiters 

• Names 

• Line numbers 

• Numeric constants 

• Character string constants 

• Operators 

• Comments 


Delimiters 

A delimiter is a character or a pair of characters that separate or mark the beginning 
or end of a token. The debugger recognizes delimiters for names, lines, 
commands, strings, range specifications, modules, lists, and comments. Table 3-1 
lists the delimiters. 


Table 3-1 Special Character Delimiters 


Character 

Description 

Function 





Space 

Blank separator 


Tab 

Blank separator 

<cr> 

Carriage return 

Line terminator 

& 

Ampersand 

Continuation line indicator 


Semicolon 

Command separator 


Apostrophe 

String delimiter 


Dot 

Compound name separator 


Quotation marks 

User symbol flag 


Colon 

Module name prefix 

, 

Comma 

List separator 

!% 

Slash asterisk 

Start-of-comment delimiter 

*/ 

Asterisk slash 

End-of-commment delimiter 
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Names 

There are three types of names: 

• Keywords 

Keywords are reserved elements of the debugger command language. Key- 
words have special meaning within the debugger language and, therefore, 
cannot be used in other ways. For example, a keyword cannot be used as a 
debug symbol. Appendix G contains a complete list of PSCOPE keywords. 

• Program symbols 

The compiler includes program symbol information in your object file when 
you compile your source module with the compiler DEBUG control. The 
debugger enters the program symbols into its symbol table when you load 
your object code. 

• Debug symbols 

Debug symbols are any symbols defined by the user in a debug session. 
Chapters 7 and 8 describe debug symbols and their use. 


Names Format 

A name is a sequence of letters, digits, underscores, at-signs, question marks, or 
dollar signs, of which the first character must be a letter, underscore, at-sign, or 
question mark. This format is summarized in Table 3-2. 


Table 3-2 Names Format 


Valid 

First Character 

Valid 

Remaining Characters 

Description 

A-Z 

-Z 

Letters 

@ 

@ 

At-sign 

? 

? 

Question mark 


0-9 

Digits 


$ 

Dollar sign* 

- 

- 

Underscore 


‘Embedded dollar signs are ignored by the debugger and may be used to improve the readability of a 
name. 


To convert Pascal labels (which are numbers in the source code) to the name 
format, the compiler removes leading zeros from each label and attaches a leading 
at sign (@) to the label. For example, the label '9999' in module 'DC' is as follows: 

:DC.@9999 

The debugger accepts names of unlimited length; however, it uses only the first 40 
characters. The debugger interprets uppercase and lowercase characters as the 
same character (i.e., b and B are interpreted as the same character). 


Referencing Names 

Names have the following precedence: command keywords, debug symbols, pro- 
gram symbols. The debugger checks symbols it encounters to see if they are 
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keywords. If a symbol is not a kes^vord, the debugger checks to see if it is the name 
of a debugger object. If the symbol is not the name of a debugger object, the debug- 
ger assumes that the symbol is the name of a program object. 

A debug symbol must not duplicate a keyword. A debug ssmibol is referenced by 
entering its name. 


A program symbol name may duplicate a keyword or debug symbol if you precede 
it with quotation marks (") , as shown in the following example: 

FOO + "Line 

In all cases, you can reference a program symbol by using a fully qualified name. A 
fully qualified name is a compound name, where each level of the name is specified 
beginning with the module name, including any names of enclosing procedures, 
and ending with the symbol name. For example, use the following reference for 
the variable “TEST” in procedure “GETSCORE” of module “SYSTEM”: 

:SYSTEM.GETSCORE.TEST 

Alternatively, you can use a partially qualified reference depending on where you 
are in the program. A partially qualified reference lets you abbreviate the reference 
by omitting leading parts of the reference, such as the module name. This method 
is explained further in Chapter 5. 


Line Numbers 

The compiler produces line numbers. The following format is for a line number 
reference. 

[-.module-name] *Une-number 

For example: 

:M0D1#23 

or 

#23 

Note that module names must begin with a colon (;), as shown in the first 
example. 


Numeric Constants 

Numeric constants are integers or floating point numbers. 


Integers 

An integer constant is a number consisting of one or more digits and an optional 
one-character suffix that identifies the number base. The suffix is not required if 
the integer’s number base corresponds to the current default base set with the 
BASE command. (Note that a 0 (zero) must precede hexadecimal numbers begin- 
ning with the letters A through F to distinguish them from names.) 

You can enter alphabetic hexadecimal digits A through F and base suffixes (Y, T, 
H, K) in either uppercase or lowercase. 
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Table 3-3 summarizes integer constants. 


Table 3-3 Elements of Integer Constants 


Number Base 

Valid Digits 

Suffix 

Example 

Binary (base 2) 

0,1 

Y 

11110011Y 

Decimal (base 10) 

0-9 

T 

243T 

Hexadecimal (base 1 6) 

0-9, A-F 

H 

0F3H 

Decimal multiple of 1 024T 

0-9 

K 

4K 


Floating Point Numbers 

Floating point numbers are decimal numbers consisting of a significand 
(expressed in one or more digits) , a decimal point, one or more additional digits, 
and an optional exponent. The exponent consists of the letter E followed by a 
signed integer value. For example, the following decimal value: 

0.24x10-2 

May be expressed as follows: 

0.0024 

or 

0.24E-2 

Use the following guidelines when working with floating point numbers: 

• You must use the decimal point in a floating point number to distinguish the 
E as a scale factor (e.g., 44.0E30); otherwise, E might look like a digit in a 
hexadecimal number (e.g., 44E30). 

• Digits must appear on both sides of the decimal point. For example, 0.85E2 
and 85.0E2 are acceptable, but .85E2 is not because there is no digit before 
the decimal point. 

• A floating point number must have a value in the following range: 64-bit 
mantissa, 15-bit exponent, and a sign bit, for a total of 80 bits. 

Floating point (real) arithmetic used in PSCOPE conforms to the proposed IEEE 
standard for binary floating point arithmetic. This standard specifies internal data 
representations, normalization, rounding modes, and error handling. All real 
arithmetic performed by Intel microprocessors and software (except VSP 
software) conforms to this standard. {The 8086 Family User's Manual QxpXdlm the 
proposed IEEE floating point standard.) 

Character String Constants 

The term string in a command format means a sequence of one or more ASCII 
printing characters enclosed in delimiters of apostrophes. Examples are as follows: 

'ABCDE' 

Testing 12 3' 

'X' 

THIS IS A STRING' 

'This is a string' 
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To enter a literal apostrophe inside a string, use two apostrophes to distinguish the 
literal apostrophe from those used as delimiters. 

For example, the following; 

'WHAT"S UP?' 

Is stored as follows: 

WHAT'S UP? 

The debugger accepts strings of up to 254 characters, not counting the enclosing 
delimiters. You can extend strings over more than one line; the debugger concate- 
nates (links) adjacent strings into a single string. You can separate adjacent strings 
with spaces, tabs, or carriage returns. 

When a string value is stored in memory, the value is the one-byte ASCII value of 
each character. If the string has more than one character, the debugger stores the 
subsequent ASCII values in consecutive locations. 


Operators 

The command language contains tokens that serve as operators. Table 3-4 lists the. 
special character operators that the debugger recognizes. 


Table 3-4 Special Character Operators 


Operator 

Description 

Function 

* 

Multiply sign 

L Multiplication 

_ 

Minus sign 

Negation or subtraction 

+ 

Plus sign 

Identity or addition 

/ 

Slash 

Division 


Double equal 
signs 

Equality 

<> 

Angle brackets 

Inequality 

> 

Angle bracket 

Greater than 

< 

Angle bracket 

Less than 

> = 

Bracket, equals 

Greater than or equal to 

< = 

Bracket, equals 

Less than or equal to 


Dot 

Address of (prefix operator) 

’() 

Parenthesis 

Bracketing 

[] 

Square brackets 

Array indexing 

== 

Equal sign 

Assignment 


Colon 

Pointer constructor 


In addition to the special character operators shown in Table 3-4, PSCOPE also 
supports several keyword operators. OR, XOR, AND, and NOT are the conven- 
tional Boolean operators. MOD is the conventional remainder (or modulo) opera- 
tor (as defined in Pascal) , extended to also work with real numbers. 
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Comments 

The debugger ignores characters enclosed by the comment delimiters, /* and »/. 
The following comments would be ignored by PSCOPE: 

/* THIS PROGRAM WAS DEBUGGED WITH PSCOPE */ 

/* THIS COMMENT IS 
SPREAD OVER TWO LINES. »/ 


Types of Symbol Objects 

All objects referred to by debug or program symbols have an associated type. Sym- 
bols are divided into three types. The first two types, memory and debug, are basic 
types whose names and definitions are determined by PSCOPE. The third type, 
referred to as user types, consists of user-defined symbols. PSCOPE obtains this 
type of information from the debug information in the load module of a program. 
Table 3-5 lists the standard types recognized by the debugger. 


Table 3-5 Standard Symbol Object Types 


Symbol 

Type 


Object Type 


Definition 


Memory 


BOOLEAN 

CHAR 

POINTER 


TRUE or FALSE 

String of ASCII character(s) 

Pointer value 


WORD 

DWORD 

SELECTOR 

ADDRESS 

SHORTINT 

INTEGER 

LONG I NT 

EXTINT 

BCD 


UnSiyii0u o-uii CjUantity 
Unsigned 16-bit quantity 
Unsigned 32-bit quantity 
Unsigned 16-bit quantity 
Unsigned 16-bit quantity 
Signed 8-bit quantity 
Signed 1 6-bit quantity 
Signed 32-bit quantity 
Signed 64-bit quantity 
Signed 1 8-digit binary coded 
decimal number 


REAL 

LONGREAL 

TEMPREAL 


32-bit floating point number 
64-bit floating point number 
80-bit floating point number 


Debug 


PROC 

LITERALLY 

BRKREG 

TRCREG 

PATCH 


Debug procedure 
String macro 
Break register 
Trace register 
Debug patch code 


User 


ARRAY 

RECORD 


Array 

Pascal record or PL/M 


PROCEDURE 

LABEL 

LINE 

FILE 

MODULE 

ENUMERATION 


structure 

User program procedure or 
function 

User program label 
User program line number 
User file 

User program module 
User-defined PASCAL 


enumerated type 
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Compiler/Assembler Type vs. PSCOPE Type Names 

PSCOPE does not always identify a program variable as the same memory type as 
the user program. For example, PSCOPE considers an ASM-86 program variable 
of type DWORD to be a program variable of type POINTER. Table 3-6 lists the 
memory type differences between ASM-86, PL/M-86, Pascal-86, FORTRAN-86, 
and PSCOPE. 


Table 3-6 Compiler/Assembler Type vs. PSCOPE Type Names 


ASM-86 

PSCOPE for ASM- 

-86 



PL/M-86 

PSCOPE for PL/M-86 

BYTE 

BYTE 

BYTE 

BYTE 

WORD 

WORD 

WORD 

WORD 



INTEGER 

INTEGER 



SELECTOR 

SELECTOR 

POINTER 

POINTER 

POINTER (small) 

ADDRESS 



POINTER (compact 

POINTER 



or large) 


DWORD 

POINTER 

DWORD 

DWORD 



REAL 

REAL 

QWORD 

LONGREAL 



TBYTE 

TEMPREAL 



STRUG 

RECORD 

STRUCTURE 

RECORD 

RECORD 




RFIELD 




STRUG 

ARRAY OR RECORD 

STRUCTURE ARRAY 

ARRAY OF RECORD 

ARRAY 




Pascal-86 

PSCOPE for 

FORTRAN-86 

PSCOPE for 


Pascal-86 


FORTRAN-86 

BOOLEAN 

BOOLEAN 

LOGICAL*1 

BOOLEAN 

CHAR 

CHAR 

INTEGER*1 

SHORTINT 



CHARACTER*n 

CHAR 

WORD 

WORD 

LOGICAL*2 

WORD 

INTEGER 

INTEGER 

INTEGER»2 

INTEGER 

LONGINT 

LONGINT 

LOGICAL*4 

DWORD 

REAL 

REAL 

REAL*4 

REAL 



INTEGER*4 

LONGINT 

LONGREAL 

LONGREAL 

REAL*8 

LONGREAL 



DOUBLE PRECISION 


TEMPREAL 

TEMPREAL 

TEMPREAL 

TEMPREAL 

RECORD 

RECORD 



ARRAY 

ARRAY 



FILE 

FILE 



SET 

SET 




Pascal-86 uses POINTER types to allocate, access, and de-allocate dynamic 
variables. Pascal POINTERS are not analagous to PL/M-86 POINTERS. 
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Expressions 

Expressions can be used as command arguments to specify numeric. Boolean, or 
string values. 

Expressions can be one of the following: 

• A single number, constant, or symbolic reference. Example areas follow: 


0 (N umber without explicit suffix) 

1 OOH (Hexadecimal numeric constant) 

'A' (One-character string constant) 

X (Symbolic reference yielding a value) 

• A formula applying operators and functions to numbers, constants, and sym- 
bolic references as operands. 

The debugger performs the calculation, using parenthetical and operator 
precedence and left-to-right order to determine the sequence of operations. 

Examples of expressions are as follows: 

2 + 3 
174/4 

OlOOH + OOFH 
2 » (6 + 4) 

.BUFFER + 2 

. ■» 1 in * iT I ^ -I 

:iviujJ'i.o/\ivi T zi 

To evaluate and display the value of an expression, enter the expression. An ex- 
pression evaluates to a type component and a value component. The rules for 
determining expression types and values are discussed later in this chapter. 


Operands 

You can use the following types of operands in expressions: 

• Numeric constants 

• String constants 

• Program symbol references 

• Machine register references 

• Memory references with explicit typing 

• Line number references 

• Debug variable references 

• Debug procedure calls 

• Debug procedure parameters 

• Debug built-in function calls 
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Numeric Constants 

Numeric constants can be integers or floating point numbers, described previously 
in this chapter. 


String Constants 

You can use character strings as arithmetic values in expressions, as follows: 

• A one-character string, which has a byte value corresponding to the charac- 
ter's ASCII representation. For example, the string constant 'A' has the 
value 41H. 

• Longer string constants (up to 254 characters) , which you may also use as 
parameters of debug procedures or as arguments to built-in string functions. 


Program Symbol References 

When you enter a program symbol reference as an operand, its value is obtained 
from the debugger symbol table and used in the associated expression. 

To reference the value of a program symbol, use the following format: 

symbolic-reference 

Where: 

symbolic-reference is a fully or partially qualified reference as described 
in Chapter 5. 

To reference the address of a program symbol, prefix symbolic-reference with the 
dot operator as shown in the following example: 

. symbolic- reference 


Machine Register References 

You can reference the 8086 registers symbolically, within expressions, just like 
variables. 

The registers are as follows: 


AH 

AL 

AX 

BH 

BL 

BP 

BX 

CH 

CL 

CS 

CX 

DH 

DI 

DL 

DS 

DX 

ES 

FH 

FL 

FLAG 

IP 

SI 

SP 

SS 


Memory References with Explicit Typing 

To reference a memory location and interpret it as a particular type of object in an 
expression, use the following format: 

memory-type location 
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Where: 

memory-type is one of the object types shown in Table 3-5. 

location is an expression that evaluates to a pointer. The pointer must 
refer to a single valid address. 


The memory reference format uses memory-type to interpret the area of memory 
pointed to by the address expression. The following example: 

BYTE .FOO 

interprets the first byte at the address of FOO as a byte regardless of the type of 
FOO. 


Other examples of memory references are as follows: 

BYTE (.buffer -I- bufindex) 

WORD DS:22H 
X + (INTEGER .ABLE) 

(LONGREAL TEST) MOD 5 


Line Number References 


When you use a line number reference in an expression, you get the address of the 
first instruction generated by the compiler for the source line number. In other 
words, you are referencing a program location through the line number. 


If diffeient niodulcs (each with then own stateuient numbers) are linked, you 
must sometimes specify a module name in the line number reference, as follows: 


[.module] * line-number 

You must use fully qualified line references (those with a module specified) when 
referring to a line number that is not in the current default module (determined by 
the current name scope) . You can use partially qualified references (those without 
a module name) when the line reference is in the current default module. 


The statement number must be a decimal integer. Examples of line number refer- 
ences are as follows: 


#45 

:TEST#1 

#23 


Debug Variable References 

After defining a debug variable (described in Chapter 7), you can use its value as 
an operand within an expression. PSCOPE also includes the following predefined 
variables: 


Name Object Type 

BASE BYTE 

NAMESCOPE POINTER 

$ POINTER 


Use 

Current default numeric base 

Starting point for program symbol 
lookup 

Value of CS:IP 
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Debug Procedure Calls and Parameter References 

After defining a debug procedure within the debugger (described in Chapter 8) , 
you can call that procedure from within an expression and have it return a value. 

PSCOPE includes several built-in functions, as follows: 


Name 

Use 

SUBSTR 

Substring selection (Chapter 10) 

CONCAT 

String concatenation (Chapter 10) 

STRLEN 

String length (Chapter 10) 

Cl 

Console character input (Chapter 10) 

ACTIVE 

Testing for program symbol accessibility (Chapter 5) 

SELECTORSOF 

Segment portion of pointer (Chapter 10) 

OFFSETSOF 

Offset portion of pointer (Chapter 10) 


Operators 

An expression can contain any combination of unary and binary operators. 


The debugger recognizes five groups of operators: dereference operators, pointer 
selector operators (pointer selection uses built-in functions), arithmetic 


operators, memory-type operators, relational operators, and logical operators. 


Table 3-7 shows the operators in each group in descending order (from highest to 
lowest precedence). In the table, all operators apply to both real and integer oper- 
ands unless otherwise noted. All operations are binary unless specified as unary 
operations. 
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Table 3-7 Precedence of Operators (Highest to Lowest) 


Group 

Operator 

Operation 

Precedence 

Arithmetic 

+ 

Unary plus 

1 


- 

Unary minus (2’s complement) 



* 

Multiplication 

2 


/ 

Division 



MOD 

Integer remainder 



-1- 

Addition 

3 



Subtraction 


Relational 

- — 

is equal to 

4 


> 

Is greater than 



< 

Is less than 



> = 

Is greater than or equal to 



< = 

Is less than or equal to 



< > 

Is not equal to 


Logical 

NOT 

Vs complement 

5 


AND 

Logical AND 

6 


OR 

Logical OR 

7 


XOR 

Exclusive OR 


Memory 

BOOLEAN 

TRUE or FALSE value 

8 

Type 

CHAR 

8-bit ASCII character 



POINTER 

Pointer value 



BYTE 

Unsigned 8-bit quantity 



WORD 

Unsigned 16-bit quantity 



ADDRESS 

Unsigned 16-bit quantity 



SELECTOR 

Unsigned 1 6-bit quantity 



DWORD 

Unsigned 32-bit quantity 



SHORTINT 

Signed 8-bit quantity 



INTEGER 

Signed 16-bit quantity 



LONGINT 

Signed 32-bit quantity 



EXTINT 

Signed 64-bit quantity 



BCD 

Signed 1 8-digit binary coded 




decimal number 



REAL 

32-bit floating point number 



LONGREAL 

64-bit floating point number 



TEMPREAL 

80-bit floating point number 



Type Conversions 

PSCOPE automatically converts values from one type to another during expres- 
sion evaluation and during modify commands (described in Chapter 7) . 

The following type classification is useful for describing the type conversions per- 
formed by PSCOPE. The numbers in parentheses are the number of bytes used to 
store a value of that type (precision). The type in each class considered to have the 
maximum precision for that class is listed at the bottom of each column. 
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Unsigned 

Signed 

Real 

BYTE (1) 

SHORTINT (1) 

REAL (4) 

WORD (2) 

INTEGER (2) 

LONGREAL (8) 

ADDRESS (2) 

LONGINT (4) 

EXTINT (8) 

SELECTOR (2) 


BCD (10) 

DWORD (4) 


TEMPREAL (10) 


Note that Pascal enumeration types are treated as unsigned types of the smallest 
precision necessary to hold the ordinal representation of that type. 


Type Conversions for Expressions 

The automatic type conversions that PSCOPE performs during expression evalua- 
tion are dictated by the following two things: 

• The type of value expected by an operator or function. 

• Not losing any significant portion of a value when performing an operation. 

To accomplish these objectives, PSCOPE performs the following type conversions 
during expression evaluation: 

1. Each value used by the operation is extended to the maximum precision for 
that type class. 

2. Each value is converted to the type required by the operation. 

3. The operation is performed, and the resulting value is left in its maximum 
precision and passed on as a value to other operations in the expression (if 
any). 


Type Conversions for Assignments 

The type of the source value and the type of the target variable dictate the automat- 
ic type conversions PSCOPE performs during assignment. In general, the type 
conversion proceeds as follows: 

1 . The source value is extended to the maximum precision for its type class. 

2. The resulting value is converted to the maximum precision type of the type 
class of the target variable. 

3. The resulting value is truncated to the exact precision required for the target 
variable type. 

There are a few minor exceptions to these rules when non-numeric types are in- 
volved (CHAR, POINTER, and BOOLEAN) . In these cases, conversions between 
some types may not be allowed or are handled as special cases. However, even for 
these types, the automatic conversions performed by PSCOPE extend those 
provided by Pascal and PL/M. 
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CHAPTER 4 
LOADING AND 
EXECUTING PROGRAMS 


This chapter describes how to load programs and control execution by setting 
breakpoints with the GO command and by stepping through the program. 

The LOAD Command 

The LOAD command loads the program file you want to debug. With the LOAD 
command, you can specify that certain debugging information not be loaded, that 
the 8087 emulator be linked with the program file (ISIS and iNDX only) , or that 
8087 chip support be included (iRMX-86 only) . 


Syntax 

LOAD file [load-Option]* [CONTROLS command-tall] 

Where: 

file is the name of the program file you want to debug. 

This name may be a complete pathname. 

load-option is one of the following: 

E8087 informs PSCOPE that your program uses the 8087 soft- 

ware emjjlator. Select this option if your program per- 
forms real arithmetic and PSCOPE is running under 
the ISIS or iNDX operating systems. ( The 8087 Support 
Library Reference Manual contains information on the 
8087 emulator and numeric support.) 

CH8087 informs PSCOPE that your program uses the iSBC® 
337 MULTIMODULE™ (the 8087 hardware). Select 
this option if your program performs real arithmetic 
and PSCOPE is running under the iRMX-86 operating 
system. 

NOLINES specifies that line number information is not loaded 
from the program file. 

NOSYMBOLS specifies that symbol information is not loaded from 
the program file. 

command-tail is any arbitrary text expected by your program. For 
example, if your program expects parameters on its 
invocation line, (a PL/M-86 program that uses the 
DQ$GET$ARGUMENT system call), those parame- 
ters would appear here. 


Description 

The load command loads the specified file into the microcomputer system 
memory. The debug information in file is processed to produce PSCOPE’s symbol 
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table of information about the loaded program. If necessary, PSCOPE sends part 
of this symbol table to disk, using a temporary work file. 

The controls command lets you specify information your program may need to 
execute. 

You can extend the invocation line as you would any command line. 

The object file must conform to the 8086 object module formats. The object pro- 
gram must be position independent code (PIC) or load time locatable (LTL) , with 
absolute segments for interrupt vectors only. Because they do not use absolute 
addressing, PIC and LTL object programs are less likely to cause conflicts with 
PSCOPE’s address base. PSCOPE issues an error message if you try to load a pro- 
gram which is neither PIC nor LTL. 

The loaded object file must contain information initializing the CS, IP, SS, and DS 
8086 registers. If these registers are not initialized during loading, PSCOPE dis- 
plays an error message. 

PSCOPE removes all previously set break registers (BRKREGs) , trace registers 
(TRCREGs), and patches when you load a program, even if the load is 
unsuccessful. 


Example 

The following example uses the LOAD command. 

«LOADdc.86 

The GO Command 

The GO command transfers execution control to the loaded program. 


Syntax (simplified) 

GO [TIL expression [, expression]*] 


or 


GO FOREVER 
Where: 


expression is a symbolic expression specifying an address in the program 
code where you want a breakpoint. 


Description 

The GO command transfers control from PSCOPE to the program under debug 
and specifies the conditions under which the user program stops executing and 
transfers control back to PSCOPE. 

TIL lets you specify any number of breakpoints. Breakpoints are stopping points at 
specific addresses in your program.. 
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GO FOREVER specifies that youf program will be executed without breakpoints. 

If you do not specify neither TIL nor FOREVER, control passes to your program 
using the same breakpoints as those used by the previous GO command (if any) . 

During program execution, you can interrupt execution any time by entering 
CNTL-C. Note that entering CNTL-C while your program is executing the UDI 
primitive DQSRead from :CI: causes an end of file condition on :CI:. The sample 
program DC (found in Appendix E) is included on the PSCOPE disk and shows 
one way of avoiding this problem in its procedure GET_LINE. 

Note that the GO command always executes at least one instruction, so you can 
set a breakpoint at the current execution point. 

Chapter 1 1 explains how to use the GO command with break and trace registers. 


Example 

Each of the following examples is based on the sample program DC found in Ap- 
pendix E. 

The following example executes the program using two breakpoints, one set at a 
specific statement and the other set at the address of a procedure. 

*go til :dc# 26 , :dc.gettoken 

The following example executes using the previous breakpoints: 

*go 

The following example executes using no breakpoints at all: 

«go forever 


The LSTEP and PSTEP Commands 

The LSTEP and PSTEP commands let you single-step through the program by ex- 
ecuting numbered (high-level) language statements. 


Syntax 

LSTEP 


or 


PSTEP 


Description 

PSTEP and LSTEP are PSCOPE’s source-level statement stepping commands. 
PSTEP treats a procedure or function as a single statement, executing it entirely 
before returning control to you at the next statement. LSTEP steps through proce- 
dures and functions one statement at a time. 
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IF you enter PSTEP or LSTEP from a normal command level, PSCOPE returns 
the following message after executing the statement; 

[Step at line-number] 

Where: 

line-number refers to the current execution point, after the step is 
complete. 

PSCOPE does not print a message if either command is issued from a nested 
PSCOPE command (DO, IF, COUNT or REPEAT). 

PSTEP and LSTEP must be entered when the execution point is at the start of a 
statement. Note that any code patches are executed when stepping, but that no 
other user-set breakpoints are active (run-time exceptions, however, are still 
trapped) . 

Note also that both PSTEP and LSTEP require line information; stepping from a 
location with line information into one without it causes execution to continue 
until a known line is reached. 


Example 

The following example uses the PSTEP command. 

^pstep 


The ISTEP Command 

The ISTEP command allows you to single-step your program through assembly 
language instructions. 


Syntax 

ISTEP 


Description 

The ISTEP command executes one assembly language instruction, displays the 
next assembly language instruction to be executed, then halts. When stepping 
through an intruction that alters a segment register the step will execute two 
instructions. 
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CHAPTER 5 
EXAMINING AND MODIFYING 
PROGRAM SYMBOLS 


This chapter describes how to reference objects (variables, procedures, etc.) in a 
program you have loaded and how to display and modify program objects. It ex- 
plains the concept of current name scope (CNS) and how CNS allows abbreviated 
(partially qualified) references to program symbols. The following commands are 
explained in this chapter: 

• Program symbol references 
Display program symbol 
Change program symbol 
Change 8086/8088 flags 
Change 8086/8088 registers 
The REGS command 
Change 8087 registers 
Change name scope 
Active function 

• Memory manipulation commands 
Display memory 

Modify memory 

The single line assembler/disassembler 


Program Symbol References 

Program symbols are produced by the compiler (when you specify the DEBUG 
option) and loaded into the debugger symbol table with the LOAD command 
(described in Chapter 4) . 


Current Name Scope 

The current name scope (CNS) is the set of symbols accessible from a specific loca- 
tion in the program, as defined by the compiler. This program location is called the 
debug cursor and changes as the program execution point changes. You can also 
change the debug cursor with the NAMESCOPE command (described later in this 
chapter). 

In a Pascal procedure, the scope of local variables is the procedure they are defined 
in; outside that scope, the symbols have either no meaning or an entirely different 
meaning. To illustrate, suppose you have two variables of the same name in two 
different procedures. In this case, specifying the variable name alone is not 
sufficient. You must also specify the procedure in which the variable is found. 

References to program symbols can be fully or partially qualified, as explained in 
the following section. 


Fully Qualified References 

A fully qualified reference always begins with a module name. It also specifies the 
name of the procedure (or procedures) containing the referenced symbol, includ- 
ing the names of all procedures enclosing the symbol. 
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Syntax 

:module-name Iprocedure’Symbof]* .symbol-reference 
Where: 

module. name is the name of the load module. 

procedure-symbol is the name of the procedure. 

symbol-reference is one of the following: 

variable-symbol is a program symbol that specifies a program 
variable. 

variable-name [qualifier]* 

variable-name is a variable name. 

qualifier is one of the following: 

left-bracket expr I expr]* right-bracket 

left- bracket and right- bracket art the characters [ and ] and 
specify array indexing. 

expr is an expression used to index an array variable. 

.field-symbol specifies a field within a record (structure) 

pointer is the character land indicates Pascal pointer 

dereferencing. 

Description 

For fully qualified references, procedure- symbols must be direct references to 
procedure names; procedure variables are not allowed. 

To illustrate, assume you want to reference a parameter named C contained in the 
function DIGIT in the procedure GET_TOKEN of module DC. Your fully quali- 
fied reference to the variable C is the following: 

:dc.get_token.digit.c 

A fully qualified reference establishes a path from the module level of the program 
down to the desired symbol. 

For example, to reference the variable named VARIABLE_INDEX of the proce- 
dure FACTOR, you must specify both the variable and the procedure containing 
it. Specifying the following: 

:dc.variableJndex 

does not work. Because PSCOPE does not know which procedure contains the 
variable VARIABLE_INDEX, it assumes that VARIABLEJNDEX is either a 
variable or a procedure declared at the main level of DC, Specifying the following: 

: dc . f actor, variable-index 

establishes a path for PSCOPE to follow to the desired variable. 
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Structures nested within other structures (or records within records) are refer- 
enced in the same way (outer to inner levels) , thus establishing a path that speci- 
fies all enclosing structures. 

Partially Qualified References 

A partially qualified reference omits some or all of the leading part of a fully quali- 
fied reference, depending on the current name scope (CNS) . 

Using the previous fully qualified reference example (:dc.get_tfeken.digit.c), you 
can use varying degrees of partially qualified references, depending upon the cur- 
rent name scope. For example, if the CNS is within the procedure GET^TOKEN, 
the partially qualified reference DIGIT.C is sufficient. If, however, the debug 
cursor is at the main level of module DC, the partially qualified reference should 
be as follows: 

get_token.digit.c 

The fully qualified reference is required when the debug cursor is in a module 
other than DC. 

The following examples illustrate fully qualified references (FQR) and partially 
qualified references (PQR) : 


FQR 

:dc.get_token.digit.c 
: dc. term . ter m_value 
dc.@9999 


PQR 

c 

digit.c 

term_value 

term.term_value 

@9999 


Required CNS for PQR 

:dc.get_token.digit 

:dc.get_token 

:dc.term 

:dc 

:dc 


Note that changing the name scope or using a more qualified reference lets you 
reference symbols outside of the symbols scope. This is useful for operations like 
setting breakpoints, patches, etc. However, referencing symbols outside of their 
scope may not let you examine the value of some local variables because the 
values are undefined outside their scope. 

Display Program Symbol 

You can obtain the value of the program symbol, like the value of an expression, 
by entering the name of the program object whose value you want. 

Syntax 

symbol-name 

Where: 

symbol-name is either a fully qualified or a partially qualified symbolic 
reference to a program symbol. 


Description 


Entering symbol-name yields a typed value. The format of the symbol value dis- 
played depends on the referenced symbol type. Table 5-1 describes default display 
formats. 
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Example 

The foliowing example references a CHAR variable C (with a value of a) in the 
sample program DC (found in Appendix E) : 

« idc.get-token.digitx 

a 

to 

a 

The following example displays the value of a field CLASS in the record T. Note 
that class is of type enumeration: 

«t.class 

3 

The following example references an element of an array within a record. Note 
that the components of the array are of type CHAR: 

*buffer.str[1] 

a 

Table 54 shows the default display formats for predefined program symbol types. 
These formats are used by the display program symbol, unformatted WRITE, and 
display memory commands. 


Table 5-1 Default Display Formats 



Predefined Symbol Types 

Type 

Display 

BOOLEAN 

Byte value displays FALSE if low order bit is 0 or TRUE if low order bit 
is 1. 

Unsigned 8-bit quantity in current base. 

BYTE 

CHAR 

8-bit ASCII character. 

WORD 

Unsigned 16-blt quantity in current base. 

DWORD 

Unsigned 32-bit quantity in current base. 

POINTER 

Pair of words as nnnninnnn (always hex). 

ADDRESS 

Unsigned 1 6-blt quantity in current base. 

SELECTOR 

Unsigned 16-bit quantity in current base. 

SHORTINT 

Signed 8-bit quantity in current base. 

INTEGER 

Signed 1 6-bit quantity in current base. 

LONGINT 

Signed 32-bit quantity in current base. 

EXTINT 

Signed 64-bit quantity in current base. 

BCD 

Signed 18-digit quantity in current base. 

REAL 

32-bit quantity in floating point notation, (always decimal). 

LONGREAL 

64-bit quantity in floating point notation, (always decimal). 

TEMPREAL 

80-bit quantity in floating point notation, (always decimal). 

ENUMERATION 

Elements displayed as ordinal number. 

ARRAY 

Array components that are predefined symbol types are displayed as 
described previously. PSCOPE does not display entire arrays or array 
components that are not predefined types. 

PROCEDURE 

Entry point address. 

LABEL 

Address. 

FILE 

No display. 

MODULE 

Address. 

RECORD 

Record fields that are predefined symbol types are displayed as de- 
scribed previously. PSCOPE does not display entire records or fields 
that are not pre-defined types. 
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Change Program Symbol 

This section shows you how to change the value of a program symbol. 


Syntax 

symbol-name = new-value 
Where: 

symbol-name is the name of a program symbol. 

new-value is the new value for symbol-name. The new-value can be an 
expression that evaluates to the correct type for the 
assignment. The expression can contain program or debug 
symbol references, constants, strings, etc. 

Description 

The new value must yield a typed value that matches the type of the program 
symbol referenced, or the new value can be forced to match under the type coer- 
cion rules given in Chapter 3. 

The debugger displays an error message if the change value yields the wrong type. 


Exampie 

The following example illustrates how to change the value of a program symbol. 

«buffer.str[buffer.index] = 'x' 

»buffer.index = buffer.index -i- 1 
*term.factor_1 -value = 0 
«:dc. variable-table ['a'] = -23 


Change 8086/8088 Flags 

PSCOPE allows you to display and modify 8086/8088 flags. 


Syntax 


FLAG 

FH 

FL 

8086/8088-flag 


1= expression] 


Where: 

expression resolves to a 16-bit number to be loaded into the FLAG 
word. 

8086-8088‘flag is a symbol representing one of the 8086/8088 flags. 

FLAG represents the flag word. 
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FH represents the upper (most significant) byte of the flag 

word. 

FL represents the lower (least significant) byte of the flag 

word. 


8086-8088 

Flag 

Description 

Type 

OFL 

Overflow flag 

BOOLEAN 

DFL 

Direction flag 

BOOLEAN 

IFL 

Interrupt flag 

BOOLEAN 

TFL 

Trap flag 

BOOLEAN 

SFL 

Sign flag 

BOOLEAN 

ZFL 

Zero flag 

BOOLEAN 

AFL 

Auxiliary flag 

BOOLEAN 

PFL 

Parity flag 

BOOLEAN 

CFL 

Carry flag 

BOOLEAN 


Interpret the FLAG word as follows: 
15 0 


X 

X 

X 

X 

OFL 

DFL 

IFL 

TFL 

SFL 

ZFL 

X 

AFL 

0 

PFL 

X 

CFL 


where X lepieseuts a dun’t-care bit. 


Description 

The FLAG word displays in the current radix. The flag names are pseudo-variables 
and may be used within an expression. 

These pseudo-variables only affect the copy of the 8086/8088 flags used by the pro- 
gram being debugged. These pseudo-variables do not affect the copy of the 
8086/8088 flags used by PSCOPE. 


Example 

To display the 8086/8088 flags, enter the following: 

*BASE=1 OY;BASE /^Setting the current radix to binary*/ 
BINARY 

*FLAG 

1111000010000110 

To set the overflow flag (OFL) enter the following: 

*OFL=TRUE 

*OFL 

TRUE 


Another way of setting the overflow flag is as follows: 

*FLAG=FLAGOR0100H 
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Change 8086/8088 Registers 

PSCOPE allows you to display and modify 8086/8088 registers. 


Syntax 

8086-8088-register [= expression] 

Where: 

expression resolves to a number to be loaded into the specified 

8086/8088 register. 

8086/8088-register is a symbol representing one of the 8086/8088 
registers. 


8086-8088 

Register 

Description 

Type 

AX 

Accumulator register 

WORD 

AH 

Accumulator high byte 

BYTE 

AL 

Accumulator low byte 

BYTE 

BX 

B register 

WORD 

BH 

B register high byte 

BYTE 

BL 

B register low byte 

BYTE 

CX 

C register 

WORD 

CH 

C register high byte 

BYTE 

CL 

C register low byte 

BYTE 

DX 

D register 

WORD 

DH 

D register high byte 

BYTE 

DL 

D register low byte 

BYTE 

CS 

Code segment register 

WORD 

DS 

Data segment register 

WORD 

ES 

Extra segment register 

WORD 

SS 

Stack segment register 

WORD 

SP 

Stack pointer 

WORD 

BP 

Base pointer 

WORD 

IP 

Instruction pointer 

WORD 

DI 

Destination index 

WORD 

SI 

Source index 

WORD 


Description 


These pseudo-variables only affect the copy of the 8086/8088 flags used by the pro- 
gram being debugged. These pseudo-variables do not affect the copy of the 
8086/8088 flags used by PSCOPE. 
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Example 

The following example illustrates how to load the AX register with 12ABH: 

«AX=12ABH 

«AX 

12AB 


The REGS Command 

The REGS command displays the 8086/8088 registers. 


Syntax 

REGS 


Description 

The REGS command displays the registers in hexadecimal regardless of what the 
current radix is. Flags are identified by mnemonic only when they are set. If no 
flags are set, the word none appears. 

The registers displayed are the four data registers (AX, BX, CX, and DX), the 
four segment registers (CS, DS, SS, and ES), the instruction pointer (IP), the 
base pointer (BP) , the stack pointer (SP) , and the two index registers (SI and DI) . 


Example 


To display the 8086/8088 registers enter the following command: 


«REGS 

AX = 0004H BX 

CS = 5588H DS 

IP = 46C7H BP 

DI=03A2H 
FLAGS: ZFL PFL 


0005H CX=OOOOH 

0188H SS=0104H 

0634H SP = 0104H 


DX = 0002H 
ES = OOOOH 
SI = 0830H 


Change 8087 Registers 


When running under the iRMX-86 operating system, PSCOPE requires that your 
microcomputer system contain the iSBC 337 MULTIMODULE (the 8087 
hardware). The MULTIMODULE resides on the 86/30 card. When loading your 
program, use the CH8087 option. 

When running under the ISIS or iNDX operating systems, PSCOPE requires that 
your program be linked with the 8087 software emulator. When loading your 
program, use the E8087 option. 

When running under the iRMX-86 operating system, PSCOPE allows you to dis- 
play and modify 8087 registers. 
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Syntax 

808 7-register [ = expression] 

Where; 

expression resolves to a number to be loaded into an 8087 register. 
808 7-register is a symbol representing one of the 8087 registers. 


8087 

Register 

Description 

Type 

STO 

Internal stack register 0 

TEMPREAL 

STl 

Internal stack register I 

TEMPREAL 

ST2 

Internal stack register 2 

TEMPREAL 

STS 

Internal stack register 3 

TEMPREAL 

ST4 

Internal stack register 4 

TEMPREAL 

ST5 

Internal stack register 5 

TEMPREAL 

ST6 

Internal stack register 6 

TEMPREAL 

ST7 

Internal stack register 7 

TEMPREAL 

FSW 

Status word 

WORD 

FCW 

Control word 

WORD 

FIA 

Instruction address 

DWORD 

FDA 

Data address 

DWORD 

FIO 

Instruction 

WORD 


Example 

To display the ST4 register enter the following command; 

*ST4 

+ 2.3596874320856382E + 00001 


Read and Write I/O Ports 


This section explains how to read and write the I/O ports. The 8086/8088 I/O 
space contains byte-wide ports and word-wide ports. The port addresses are from 
OOOOH to FFFFH. 


Syntax 


PORT 

_WPORTL 


{expr-for-port‘number)[= expr] 


Where: 

PORT identifies a byte-wide port. 

WPORT . identifies a word-wide port. 

expr-for-port-number represents the port number in the current radix. 

expr represents the data in the current radix. If the value 

takes up more than one byte, PSCOPE truncates 
the data to a byte. 
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Example 

The following example writes 10 to the port 100. The H identifies 199 as a hex 
number. The T identifies the 100 as a decimal number. The value 199H is written 
to a byte-wide port. 

*PORT(100T)=10H 

The following example writes 199 to the port 100. The H identifies the 199 as a 
hex number. The T identifies the 100 as a decimal number. The value 199H is writ- 
ten to a word-wide port. 

*WPORT(100T)=199H 

The following example displays the word- wide port 100. PSCOPE always displays 
the port value in hexadecimal, regardless of what the current radix is. 

*PORT(100T) 

199 

Note that accessing ports on the microcomputer system may cause undesirable 
results. Consult the user documentation for your microcomputer system before 
you access any of its ports. 


Change Name Scope 


This sectiuii explains how to move the dcbu^ cuisui tu a new lueatiun, thus uhang- 
ing the current name scope (CNS) . 


Syntax 

NAMESCOPE [= expression] 

Where: 

expression is the location to which the debug cursor is to be reset. 


Description 

If you do not specify an expression, PSCOPE displays the address of the current 
name scope. Changing the current name scope affects the set of symbols to which 
the debugger has access. However, changing the current name scope does not acti- 
vate symbols that are not already active. 

Note that the dollar sign ($) is a predefined symbol equivalent to the current exe- 
cution point. Entering the following: 

NAMESCOPE = $ 

returns the current name scope to the current execution point. 

Resuming program execution (using GO, ESTEP, ISTEP, or PSTEP) automatical- 
ly resets the debug cursor to the current execution point. 
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Example 

The following example illustrates how changing the current name scope affects the 
lookup of a partially qualified reference to the procedure DIGIT in the sample pro- 
gram DC (found in Appendix E) : 

»get_token.digit 

1C50H:02D2H 

«digit 

DIGIT 

ERROR #12: Symbol not known in current context. 

anamescope = get_token 
iKdigit 

1C50H-.02D2H 


Active Function 

The ACTIVE function determines if a program object is active at the point where 
execution was suspended. ACTIVE will tell you if a stack-based variable is current- 
ly allocated and accessible. 

ACTIVE (symboliC’reference) 

Where: 

symbolic-reference is any program symbol, fully or partially qualified. 


Description 

ACTIVE is a Boolean function which indicates whether a symbolic-reference 
to a program object that can be displayed or modified at the current execution 
point. Statically allocated variables are always active. Dynamically allocated 
(stack-based) variables are active if they are available in the current (top) stack 
frame. ACTIVE returns a TRUE if symbolic-reference is active and a FALSE if it is 
not. 


Example 

^ACTIVE (:dc.factor.expression_value) 
TRUE 

*if ACTIVE(op) then write 'op = ',op 
■ * else write '-op not active-' 

• «endif 
-op not active- 


Display Memory 

This section explains how to display the contents of one or more memory 
locations. 
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Syntax 

memory- type start-address [fength-specifiei] 

Where: 

memory-type is one of the predefined memory types listed in Table 5-1 . 

start-address is the address of the first location in memory to be 

displayed, expressed with an expression. Recall that you 
can obtain the address of a symbol by prefixing the 
symbol with the dot operator. 

length-specifier is one of the following: 

LENGTH expression specifies the number of adjacent objects of the 
specified memory type to be accessed. 

TO end-address specifies the last address of a range of memory to 
be displayed. 

Description 

You can specify portions of memory you want displayed using memory-type 
(indicates the memory type to be used in displaying that portion of memory) . The 
memory address is displayed first (as a pointer value), followed by the value (s) at 
that location. 

Exampie 

The following example illustrates using the display memory command. 

«char .buffer.str[1 ] to .buffer.str[buffer/1ength] 

1CCBH:0018H '1 +2 + 3 + 4 + S + ' 

The following example references the CHAR variable c, (in the sample program 
DC found in Appendix E) as a BYTE. Displaying memory as BYTE values also dis- 
plays them as CHARs, as shown here: 

«byte .c 

1CCBH:0074H 97 'a' 


Modify Memory 

This section explains how to modify the contents of one or more memory 
locations. 

Syntax 

mem-type start-addr[iength-specifier] = chg-value 
Where: 

mem-type is one of the memory types shown in Table 5-1. 

start-add r is the first memory address to be displayed. 
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length-specifier is one of the following: 

LENGTH expression specifies the number of adjacent objects of the 
specified memory type to be displayed. 

TO end-addr is the last address of a range of memory to be 

displayed. 

chg-value is the new value to which the contents of the specified 

memory locations are to be set; chg-value is one of the 
following: 

expression [, expression]* 
mem-type start-addr [length-specifier] 


Description 

The change value must be of a type that either m_atches the m.em-ory type or can be 
forced to match under the type coercion rules given in Chapter 3. The debugger 
displays an error message if the change value is the wrong type. 


Example 

The following example initializes the first five values in the array “variable-table”: 

^integer .variable-table = 2, 4, 6, 8,1 0 

The following example initializes the entire contents of the array variable-table to 
0 and 1, with 0 in the first location and every other location thereafter, and 1 in the 
second location and every other location thereafter: 

^integer .variable-table length 26 = 0,1 

The following example uses the 8086 registers to reference the WORD value on 
top of the 8086 stack and set it to 0: 

«word ss:sp = 0 

The Single Line Assembler/Disassembler 

You can modify and display memory as 8086/8088/8087 mnemonics. 


Syntax 


Assignment 



address = 'assembler-mnemonic'[,' assembler-mnemonic’]* 


Display 

ASM start-address [length-specifier] 
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Where: 


SASM and ASM 


start-address 


length-specifier 


are keywords identifying the single-line assembler. 
SASM and ASM are equivalent. SASM is included 
to make the PSCOPE syntax familiar to I^ICE^^ 
users. 

is the address of the first location in memory to be 
displayed. 

is one of the following: 


LENGTH expression specifies the number of instructions to 

disassemble. 

TO end-address specifies the last address of a range of 

memory to be displayed. 


address is a single address or an expression that resolves to 

a single address. 


assembler-mnemonic is an 8086/8088/8087 instruction. 


Description 

With the disassembler, you can display memory locations as 8086/8088/8087 
mnemonics. 

With the assembler, you can load memory locations with 8086/8088/8087 
instructions. 


The Disassembler 

PSCOPE interprets the start-address as the beginning of an assembly language 
instruction. If you give a start-address that is not the beginning of an instruction, 
PSCOPE still interprets the memory location as an instruction. 

A single address displays the instruction beginning at that address. A range of ad- 
dresses {start-address TO end-addres^ displays all instructions that start within 
that range. To specify an exact number of instructions to be displayed, use the 
form, start-addressLENGTK number- of- instructions. 

The following example displays the assembly language instructions making up 
statement #16. 

« ASM :pager#1 6 TO :pager#1 7 


063CH:01F9H 

FF361C00 

PUSH 

ES:WORD PTR [SI] 

063CH:01FDH 

9A00000000 

CAII 

0:0 

063CH:0202H 

3C00 

CMP 

AL.OH 

063CH:0204H 

7403 

JE 

$+5H 

063CH:0206H 

E95401 

JMP 

$+0000AH 

063CH:0209H 

FF361400 

PUSH 

ES:WORD PTR [SI] 
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Interpret the display this way. The first entry is the starting address where the in- 
struction resides; the second entry is the hexadecimal representation of the in- 
struction (displayed in hex, regardless of what the current radix is); the third entry 
is the mnemonic representation of the instruction. 

If you did not specify a partition, you would only get the assembly language in- 
struction at the start address, as in the following example: 

«ASM ;pager#16 

01 F9 FF361C00 PUSH ES:WORD PTR [SI] 


The Single Line Assembler (SLA) 

You specify the instructions with assembler mnemonics. The SLA does not accept 
all the possible forms of the 8086 instructions (as described in the Assembler 
Operators section) . 


Assembler Directives. The SLA does not support assembler directives. For 
example, you cannot replace assembler- mnemonic mih MY_VAR DB ?. What you 
put in for assembler- mnemonic vn\xsi actually generate code. 


Assembler Operators. The SLA does not recognize ail the possible assembler 
operators. Consider the instruction MOV AL,BYTE PTR [BXj. This instruction 
would be an incorrect form for the SLA because the SLA does not recognize PTR. 
You can still put that instruction into memory with the SLA, but you must code it 
as MOV AL,BYTE [BXj. In some cases, what is a correct form for the SLA is an 
incorrect form for ASM-86. 


The assembler type operators recognized by the SLA are the following: 

BYTE Specifies a number that takes up one byte. The corresponding 
PSCOPE memory type is BYTE. 

DWORD Specifies a number that takes up four bytes. The corresponding 
PSCOPE memory type is POINTER. 

FAR Specifies that both the CS and the IP take part in a JMP or CALL. 

QWORD Specifies a number that takes up eight bytes. The corresponding 
PSCOPE memory type is LONGREAL. 

TBYTE Specifies a number that takes up 10 bytes. The corresponding 
PSCOPE memory type is TEMPREAL. 

WORD Specifies a 16-bit unsigned number. The corresponding PSCOPE 
memory type is WORD. 

segment Specifies that an operand is to be taken from a non-default 

override segment. 

prefixes 


Absolute Addresses. Unlike ASM-86, the SLA allows you to specify an absolute 
address within an instruction. For example, the SLA recognizes the instruction 
JMP 12:34. This instruction is a direct-far jump. ASM-86 would require that you 
use a label or jump indirectly through a register. 
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Like ASM-86, the SLA accepts a symbol, but the SLA requires a fully-qualified 
symbolic reference. For example, to jump to a label within the same module and 
procedure, you must code JMP imod.proc.labeL To load BX with a program 
variable, code MOV BX, .:mod.proc.var. 


Remember that PSCOPE itself consists of load-time-locatable code. So does the 
program that you are debugging. The result is that the absolute addresses corre- 
sponding to program locations may differ from application to application. Be care- 
ful only to change instructions that exist in locations assigned to your program. Do 
not change instructions in any locations used by PSCOPE. The consequence of 
this restriction is that the SLA is good for replacement patches, not for insertion 
patches. 


Also, when constructing a replacement patch, be careful not to leave part of an in- 
struction hanging. You may need to pad your replacement with NOPs. 

Jumps and Calls. The SLA expects the control transfer instruction to obey slight- 
ly different mnemonic conventions than ASM-86. Consider the five kinds of 
jumps: direct-short, direct-near, indirect-near, direct-far, and indirect-far. 

The SLA does not produce a direct-short jump. This is not a problem because you 
can use a direct- near jump instead. 

The direct-near Jump consists of three bytes. The first byte is E9, the opcode. The 
next two bytes are the difference between the current location and the destination. 


The SLA uses an absolute address as the operand for a direct-near jump. With this 
feature, you always know the destination of the jump without having to compute 
the relative offset from the current IP. For example, to load the absolute address 
IBFOOH with a direct-near instruction that jumps to absolute address 1BF05H, 
enter the following: 


«SASM 1 BFOOH= JMP 1 BF05H' 

01 BFOO E90200 


The relative displacement from the IP is 0002. This instruction skips two bytes. To 
load absolute address IBFOOH with a direct-near instruction that jumps to absolute 
address IBFFCH, enter the following: 

«SASM 1 BFOOH=='JMP 1 BFFCH' 

01 BFOO E9F9FF 


The relative displacement from the IP is FFF9H. This is a -7 in 2’s complement 
notation. 

The indirect- near jump consists of two bytes and possibly a 16-bit displacement. 
The first byte is the opcode FF, and the second byte contains the MOD field, the 
R/M field, and three more bits of the opcode (lOOY). For example, to load abso- 
lute address IBFOOH with an instruction that jumps to the offset contained in BX 
(the instruction assumes the current CS) , enter the following: 

tASfA 1 BFOOH='JMP BX' 

01BF00H FFE3 

The previous example used the keyword ASM instead of SASM. ASM is an alter- 
nate form of SASM. 

You can get another level of indirection by using brackets around the register 
name. For exam.ple, to load absolute address IBFOOH with an instruction that 
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jumps to the offset (assuming current CS) that is stored in the memory location 
whose offset is in BX (assuming the current DS) , enter the following: 

«SASM 1BF00H='JMP [BX]' 

01 BFOOH FF27 

The direct-far jump consists of five bytes. The first byte is the opcode EA, and the 
last four bytes contain the offset and the selector of the target instruction. The 
SLA recognizes a direct-far jump by the FAR operator. For example, to load loca- 
tion 3:300H with an instruction that jumps to location 12:34, enter the following: 

«ASM 3:300H='JMP FAR 1 2:34' 

0003:0300H EA34001200 

If you leave out the selector of the target address, the SLA assumes zero. For 
example, JMP FAR 34H transfers control to the location 00:34. If you specify an 
address that takes up more than 16 bits, the extra upper bits are ignored. For 
example, JMP FAR 12345H transfers control to the location 00:2345H. 

The indirect-far jump consists of two bytes and possibly a 16-bit displacement. The 
first byte is the opcode FF. The second byte contains the MOD field, the R/M 
field, and three more bits of the opcode (101 Y). For example, to load absolute ad- 
dress 1 BFOOH with an instruction that jumps to the selector and the offset 
(assuming the current CS) stored in the memory location whose offset is in BX 
(assuming the current DS) , enter the following: 

»SASM 1 BFOOH='JMP DWORD [BX]' 

01 BFOOH FF2F 

The SLA mnemonic conventions are similar for the CALL instruction. 


RETFAR 

To return from a far jump or a far call, the SLA requires the mnemonic RETFAR. 
ASM-86 knows whether a procedure is near or far, and consequently, it generates 
the appropriate return. Because the SLA does not have this information, you must 
specify whether you want a near return or a far return. With the SLA, specify a 
near return as RET and a far return as RETFAR. For example, to load absolute ad- 
dress 1 BFOOH with a far return that discards three words from the stack after 
returning, enter the following: 

«SASM 1 BFOOH='RETFAR 6' 

01 BFOOH CA0300 

Symbolic Addresses. The SLA will accept symbolic addresses, but, because the 
SLA does not use the current NAMESCOPE, you must supply a fully-qualified 
symbolic reference. For example, the SLA accepts the instruction MOV 
AX,.:mod.proc.var 

The period before the colon is a standard PSCOPE operator. It identifies the sym- 
bolic reference as resolving to the address of var and not the actual value of var. 


Multiple Forms of an Instruction. ASM-86 is a versatile assembler that often 
allows more than one version of the same instruction. For example, ASM-86 has a 
form of the MOV instruction that moves a byte from AL to a memory location. 
This form is distinct from the one that moves a byte from a register to a memory 
location. The general MOV from register to memory does contain the ability to 
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specify AL, but ASM-86 uses the shorter form because AX is the accumulator and 
hence a preferred register. 

The SLA assembles the general form and not the shorter form. For example, con- 
sider the instruction MOV SUM,AL. ASM-86 assembles this in three bytes as 
A200 OlH, assuming that lOOH is the offset of the program variable sum. The SLA 
requires a fully qualified symbolic reference for sum and assembles the same in- 
struction in four bytes as 8806 OOOIH. 

Indirect Addressing. ASM-86 allows you to express an indirect address in many 
different ways. For example, with ASM-86, the following instructions assemble to 
the same value. 

MOV AX,[BX + DI + 2] 

MOVAX,[BX] [DI][2] 

MOV AX,[BX] [DI] + 2 

The SLA only accepts the last form. The following is the general form for an indi- 
rect address accepted by the SLA. 

symbotlbasereg] [indexreg] + offset 

All the parts are optional. The brackets are part of the syntax and are required 
when you choose the option. You must choose an option in the order given. For 
example, if you construct an indirect address with a base register (BX or BP) and 
an index register (SI or DI) , the base register must precede the index register. For 
example, to load offset 21:3CH with an instruction that moves the contents of the 
AX register to memory through an indirect address, enter the following: 

«SASM 21 :3C='MOV .:cmaker.purchase[BX][SI]+300H,AX' 

0021:003CH 89801003 


This instruction loads a memory location with the contents of AX. It forms the ad- 
dress of the memory location in the following way: 

1 . Adds 300H to the offset of the address of the program variable purchase in 
the module c maker. The address of purchase \s 44:1 OH. 

cmaker. purchase 

0044:001 OH 

«DS 

0044 

2. At runtime, adds the contents of BX, the contents of SI, and the sum from 
step 1. This value is the final offset. 

3. Assumes the data segment. Gets the selector value from the DS register. 
Constructs the physical address and loads the contents of AX into the ad- 
dressed memory location. 


The Default Radix. The SLA assumes the PSCOPE current radix. You can over- 
ride the current radix for an individual number by appending a letter to the 
number. The SLA interprets a number as binary if you append a Y, as decimal if 
you append a T, as hexadecimal if you append an H, and as a multiple of 1024 
(decimal) if you append a K. PSCOPE always considers line numbers to be decimal 
regardless of what the current radix is. The SLA always displays the assembled in- 
struction in hexadecimal regardless of what the current radix is. 
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String Moves. ASM-86 provides the MOVS, MOVSB, and the MOVSW 
mnemonics. You must have previously loaded the SI and DI registers. The 
mnemonic MOVS requires two operands: the name of the destination string (the 
symbolic name for the first location) and the name of the source string. ASM-86 
uses these operands to determine whether you are moving bytes or words. The 
mnemonics MOVSB and MOVSW do not require operands because the B and W 
identify whether you are moving bytes or words. 

The SLA only accepts the MOVSB and MOVSW mnemonics. 


8087 Instructions. The SLA handles 8087 instructions differently than ASM-86. 
There are four areas of difference, as follows: 

1 . The SLA represents a stack register without the syntactic parentheses. 

2. The SLA does not recognize the ESC mnemonic. 

3. The SLA is consistent in its treatment of the 8087 no- wait mnemonics. 

4. The SLA does not recognize FWAIT. (FWAIT is an alternate way of specify- 
ing WAIT, which the SLA does recognize.) 


The Stack Registers. The SLA expects the 8087 stack registers to be STO 
through ST7 rather than ST(0) through ST (7). ASM-86 accepts ST as a symbol for 
the top of the stack. The SLA does not recognize ST; you must code STO. 


The ESC Mnemonic. The SLA supports all of the 8087 mnemonics except the 
ESC mnemonic. For example, with the SLA, you can code FADD ST0,ST1. This 
corresponds to FADD ST(0),ST(1) for ASM-86. ASM-86, but not the SLA, ac- 
cepts ESC 18H,1 as well. ASM-86 would accept both forms of the instruction and 
load memory with the word, D8C1H. 


The No-Wait Mnemonics. ASM-86 inserts a WAIT instruction before the 8087 
instruction unless you insert an N as the second character in the 8087 mnemonic. 
For example, FDISI is preceded by a WAIT; FNDISI is not preceded by a WAIT 
There is one exception. The 8087 instruction FNOP is a no-operation that does 
generate a wait. 

The SLA, however, is consistent when it interprets the second character of the 
8087 mnemonic. FNOP does not generate a WAIT; FOP does generate a WAIT. 
ASM-86 does not recognize FOP. 

In addition, ASM-86 does not allow some 8087 instructions to have the no-wait 
form. The SLA always accepts a no-wait mnemonic. 

FWAIT. FWAIT is actually not an 8087 instruction. It is an alternate form of the 
CPU instruction WAIT. The SLA considers one form to be sufficient. 
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CHAPTER 6 
CONTROL CONSTRUCTS 


This chapter describes the four control constructs used in PSCOPE’s command 
language; REPEAT, COUNT, IF, and DO. 

The IF construct conditionally executes commands. The REPEAT and COUNT 
constructs repeat a sequence of debugger commands under the control of a variety 
of exit conditions. The DO construct groups multiple commands and treats them 
as a single command. 

The level to which you can nest REPEAT, COUNT, IF, and DO control constructs 
depends upon the amount of workspace available to the debugger. 

After you enter the first line of a compound command, each subsequent line dis- 
plays a prompt preceded by a dot (.) . The dot indicates that the line is inside a com- 
pound construct. The number of dots preceding the prompt indicates the current 
nesting level. 


The REPEAT and COUNT Constructs 

The REPEAT and COUNT constructs let you repeat a sequence of debugger com- 
mands controlled by any number of exit conditions. 


Syntax 

REPEAT 

[loop-item]* 

ENDREPEAT 

or 

COUNT expression 
[loop-item]* 

ENDCOUNT 

Where: 

loop-item is any of the following: 
command is any debugger command. 

WHILE expression 
UNTIL expression 

expression is any expression that can be forced to a Boolean value. 

Description 

The loop-item of the REPEAT command executes until an UNTIL expression eval- 
uates to TRUE or until a WHILE express/o« evaluates to FALSE. 
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The COUNT command is evaluated similarly, but the number of times that the 
loop body is executed is bound by COUNT expression. COUNT expression is eval- 
uated only once, when the command is first encountered. 

If you prefer, you can use END in place of ENDREPEAT or ENDCOUNT. 


Example 

The following example uses REPEAT to implement a form of data breakpoint: 

» repeat 
• «lstep 

- xuntii :dc.c = = 

.endrepeat 

The following example steps through 10 statements and then stops: 

«COUNT10 

- *LSTEP 
.»END 


The IF Construct 

The IF construct lets you conditionally execute commands. 


Syntax 

IF expression THEN 
Icommand]* 

[ORIF expression THEN 
[command]*]* 

[ELSE 

[command]* 

ENDIF 

Where: 

expression is any expression that evaluates to a Boolean value. 
command is any PSCOPE command. 

Description 

The IF construct contains an IF clause, any number of ORIF clauses, an optional 
ELSE clause, and a closing ENDIF. 

PSCOPE evaluates IFs as follows: 

• If the IF expression evaluates to TRUE, PSCOPE executes the command list 
following the IF expression up to the first ORIF clause, the ELSE clause, or 
the ENDIF. 

• If the IF expression is FALSE, PSCOPE evaluates the subsequent ORIF 
clauses in order until it finds an ORIF expression that is TRUE, in which case 
it executes the ensuing command list up to the next ORIF clause, ELSE 
clause, or ENDIF. 
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• If the IF clause is FALSE and there are no TRUE ORIF clauses (or no ORIF 
clauses at all), PSCOPE executes the ELSE clause (if present) up to the 
ENDIF. 

• If the IF clause and no ORIF clauses are TRUE and no ELSE clause is 
present, PSCOPE resumes execution with the first executable statement fol- 
lowing the IF construct. 

You may use END, if you prefer, in place of ENDIF. 


Example 


The following example illustrates using the IF construct. 

*IF 1 = = 2 THEN 

. * THIS SHOULDN "T BE PRINTED' 
.*ORIF2 = = 2THEN 
. « THIS SHOULD BE PRINTED' 

• «ELSE 

. « THIS ALSO SHOULDN "T BE PRINTED' 
.«END 

THIS SHOULD BE PRINTED 


The DO Construct 

The DO construct lets you group commands. 


Syntax 

DO 

[commandl* 

END 

Where: 

command is any PSCOPE command (with a few restrictions, like LOAD 
and INCLUDE). 


Description 

Debugger objects defined in a DO block (using the DEFINE command described 
in Chapter 7) are local to that block and supercede any previously defined debug 
symbols with the same names. You can define global debug symbols within a DO 
block by using the GLOBAL option on the DEFINE command. 

You can nest DO blocks; however, each DO must have a corresponding END. A 
DO block is not complete (and is not executed) until PSCOPE reaches its match- 
ing END. 
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CHAPTER 7 
DEBUG OBJECT 
MANIPULATION COMMANDS 


Debug objects, which you define during the debugging session, are symbolic enti- 
ties similar to the variables and procedures in your program. Debug objects can be 
variables of any memory type, command abbreviations, debug procedures, code 
patches, or a collection of breakpoints and tracepoints. 

Note that PSCOPE uses the same commands to display, modify, and obtain a 
directory of program objects and debug objects. Program objects are part of a 
program; they are accessible to PSCOPE when the program is loaded and are inac- 
cessible when a different program is loaded. Debug objects are not tied to any par- 
ticular program. PSCOPE has explicit commands to define debug objects, to 
remove them, and to save their definitions. 

This chapter describes the following commands which are used to manipulate 
debug objects; 

Define debug object 
Display debug object 
Modify debug object 
Remove debug object 
Put/append debug objects 

Debug Objects 

Like objects in a program, debug objects have a name and a type. The DEFINE 
command which creates the debug object specifies the name and type= Debug ob- 
jects are either global or local. 

Global debug objects exist from the time you create them until you remove them 
with the REMOVE command. (The LOAD command (described in Chapter 4) 
implicitly removes some global debug objects.) Local objects can exist only within 
PSCOPE’s DO blocks. PSCOPE automatically removes them when control passes 
out of the DO block within which they were defined. 

Like keywords, debug object names have precedence over program symbol 
names. Thus, to access a program symbol with the same name as a debug object, 
you must prefix the program symbol with quotation marks ("). (“Referencing 
Names” in Chapter 3 discusses how to do this.) 

Some debug object names also have precedence over other debug object names. 
Local debug objects have precedence over global debug objects of the same name. 
Likewise, the most recently defined local debug object takes precedence over 
other local debug objects with the same name. 

You must remove a global debug object’s name (with the REMOVE command, 
described later in this chapter) before you can redefine the global debug object to 
be a different type. You can define a local debug object with the same name as a 
global debug object without affecting the definition or value of the global debug 
object. 

You cannot find the address of a debug object using the dot operator (.) explained 
in Chapter 3. PSCOPE displays an error message if you try. 

Debug objects can have any of the memory types or debug types specified in Table 
3-5. The properties of the debug objects depend on their type. 
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Memory Type Debug Objects 

In general, you can use a debug object defined as a memory type (BYTE, WORD, 
INTEGER, REAL, etc.), like a program variable of that type (in expressions, to 
display and modify). Hence, a memory type debug object is a debug variable. 

Debug variables of type CHAR have more capabilities than CHAR variables in a 
Pascal-86 program. Debug variables can be assigned string values from 0 to 254 
characters, including the results the PSCOPE built-in string functions CONCAT 
and SUBSTR return. 


Debug Type Debug Objects 

A debug object defined to have one of the five debug types listed in Table 3-5 has 
different properties from those of program objects. 

LITER ALLYs are string-replacement macros. When PSCOPE finds a symbol that 
is a LITERALLY name, it replaces the LITERALLY name with the string value 
associated with that name (just as in PL/M). LITERALLYs provide a convenient 
way to abbreviate commands and keywords. 

The debug type debug objects are as follows: 


Type 

Description 

Reference 

PROC 

Debug procedure 

Chapter 8 

BRKREG 

Group of breakpoints 

Chapter 1 1 

TRCREG 

Group of tracepoints 

Chapter 1 1 

PATCH 

Debug patch code 

Chapter 9 


You must redefine debug type objects in order to change their definitions. Use the 
EDIT command to recall the previous definition of a debug type object in order to 
redefine it. 

The DEFINE Command 

The DEFINE command creates a debug object. 


Syntax 

DEFINE [GLOBAL] type symbol-name[^ value] 

Where: 

GLOBAL indicates that the debug object will be global. Debug 

type debug objects are always global; the GLOBAL 
option is not allowed for these objects. Memory type 
debug objects are global unless they are defined inside 
a PSCOPE DO block. Hence, use the GLOBAL option 
for memory type objects inside a DO block that you do 
not want to be automatically removed when control 
passes out of that block. 

type is any of the memory tvnes or debug tvoes shown in 

Table 3-5. 
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symbol-name is any name other than a PSCOPE keyword (for local 
objects) or a keyword or existing debug object name 
(for global debug objects) . The name can be up to 254 
characters long; the first 40 characters must be a 
unique combination. 

value is the value to be assigned to the debug object. The 

value can be the result of evaluating an expression. 
PSCOPE assigns a null value if you do not give a value. 
The value is required for debug type debug objects. 
The value is optional for memory type debug objects. 


Description 

The DEFINE command creates a debug object with the name, type, and value you 
specify. If the object being defined is a memory type, the debug object has the 
same properties as a program variable of the same type. Memory type debug ob- 
jects can be any of the object types listed in Table 3-5, but cannot be a user-defined 
type. You cannot use the same name for two different debug objects unless a 
debug object is defined locally within a DO block. When PSCOPE exits the block, 
PSCOPE automatically removes the local debug object. You can then assign the 
name to another object of a different type for use in another block. 

The DEFINE command lets you optionally assign initial values to the objects 
being defined. 


Example 

The following example illustrates memory type debug variables. 

^define byte num 
xdefine integer i = 1 3 
«do 

■«define word local-word = 2 « i 
.»end 

^define char char_1 = 'this is a string' 

The following example illustrates LITER ALLYs. 

define iiteraily iit = 'literaily' 
define iit def = 'define' 
def iit el = 'evai $ iine' 


The DISPLAY Command 

The DISPLAY command displays the values of debug objects. 
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Syntax 

[type] symbol-name 
Where: 

type defines the debug symbol. If you specify type, PSCOPE 

displays the definition of the debug symbol. If you 
omit type, PSCOPE expands the symbol (for 
LITER ALLYs) or executes the symbol (for PROCs). 
You must enter type to display any of the following: 

• LITERALLY 

• PROC 

• PATCH 

• BRKREG/TRCREG 

symbol-name is the name of a previously defined debug object. 


Description 

For program symbols and memory-type debug variables, you can access the value 
of a symbol by entering the symbol name. PSCOPE displays the value of the 
symbol on the following line. Similarly, you can access the value in an expression 
by entering the name of the symbol. 

For debug objects of any of the debug types, you can access the definition of the 
debug object by entering the type, followed by the symbol name. PSCOPE displays 
the definition of the named object. 


Example 

Suppose you defined a memory type debug variable as follows: 

* define word w1 =400 

Entering the symbol name yields the following value: 

*w1 

400 

However, a debug type debug object functions differently. Consider the following 
LITERALLY definition: 

^define literally w = 'write' 

Entering w by itself automatically expands the LITERALLY, as though you en- 
tered write. You can display w definitions by preceding the w with its type, as 
follows: 

« literally w 

PSCOPE responds by printing the following: 
define literally W = 'write' 
which is the definition of w. 
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The MODIFY Command 

The MODIFY command modifies the previously defined value of a memory type 
debug symbol. 


Syntax 

name — value 
Where: 

name is the name of a memory type variable. 

value is the new value to be assigned to the debug symbol. 


Description 

The type of value must be the same as name's type, or you must be able to force 
that type (using the type coercion rules described in Chapter 3). PSCOPE displays 
an error message if the change is not possible. Note that the MODIFY command 
for debug memory type variables has the same syntax as the MODIFY command 
for program symbols. 

The MODIFY command works only with memory type objects. You must redefine 
a debug type object in order to modify it. 


Example 

The following example shows the operation of the MODIFY command: 

^define integer i = -1 50 
»i 

-150 
*i = —2 * i 
*i 

+300 


The REMOVE Command 

The REMOVE command deletes one or more debug symbols from the debug 
symbol table by symbol name and object type (or by symbol name or object type) . 


Syntax 

REMOVE remove-list 
Where: 

remove-list is one of the following: 
DEBUG 
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remove-item [, remove-item]* 
remove-item is one of the following: 

memory-type is one of the memory types given in Table 
3-5. PSCOPE deletes all debug symbols of 
the specified type. 

debug-type is one of the debug-types given in Table 

3-5. PSCOPE deletes debug symbols of the 
specified type. 

PATCH expression is an expression yielding an address where 
you set a patch. PSCOPE removes the 
patch at this location. 

symbol-name is the name of a debug symbol of any 
memory type or debug type (except patch) . 
PSCOPE deletes the specified symbol. 


Description 

The REMOVE command deletes global debug objects. The user specifies the 
debug type or the memory type object (or a list of objects) to be deleted by type 
and name (or by type or name). Specifying DEBUG instead of a list of types and 
names (or a list of types or names) removes all debug objects. 

Do not use the REMOVE command to delete local debug objects; FSCOFE auto- 
matically deletes them once control passes out of the PSCOPE DO block in which 
they are defined. 


Example 


The following examples use the REMOVE command. 


* remove proc 

* remove i 
^remove debug 
« remove proc, I 


/* Remove all PROCs */ 

/* Remove the single object i */ 
/* Remove all debug symbols */ 
/* Remove all PROCs and i */ 


The PUT and APPEND Commands 

The PUT and APPEND commands save the definitions of the debug objects in a 
disk file. 


Syntax 

PUT pathname put-list 
APPEND pathname put-list 
Where: 

pathname is the path name which identifies a file (or any output device) 
to which you want to send the text containing the debug object 
definitions. 
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put-list is one of the following; 
DEBUG 


put-item [, put-item]* 
put-item is one of the following: 


memory-type is one of the memory types given in Table 
3-5. PSCOPE saves the definitions of all 
debug symbols of the specified type in the 
specified file. 


debug type is one of the debug types given in Table 

3-5. PSCOPE saves the definitions of all 
debug symbols of the specified type in the 
specified file. 

PATCH expression is an expression yielding an address where 
you set a patch. PSCOPE saves the patch at 
this address in the specified file. 

symbol-name is the name of a debug symbol of any 
memory type or debug type (except 
PATCH). PSCOPE saves the definition of 
the specified debug symbol in the specified 
file. 


Description 

The PUT and APPEND commands place definitions of the specified objects in the 
selected disk file (or the specified output device) . (You can retrieve the definitions 
with the INCLUDE co m mand described in Chapter 10.) 

PUT creates a new file to contain the specified definitions, unless a file of that 
name already exists. In that case, PUT replaces the old file with a new file contain- 
ing the definitions. 

APPEND adds onto the end of an existing file or creates a new file if the specified 
file does not already exist. 

For debug type debug objects, the entire definition text (including the value 
portion) is placed in the specified file. For memory type debug variables, only the 
type and name are included in the object definition because memory type debug 
objects can be easily changed using the modify command, whereas debug type 
debug objects must be redefined. 

Note that except for the file specification, the formats of the PUT and APPEND 
commands are identical to the REMOVE command's format. 

Example 

The following example illustrates using the PUT command. 

«define literally lit = 'literally' 

^define lit def = 'define' 

«def lit stacktop = 'word ss:sp' 

«def integer 1 = 13 
*def word j = 1 00 
«put defs.mac debug 
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The file DBFS. MAC contains the following: 

define literally lit = 'literally' 
define literally def = 'define' 
def literally stacktop = 'wordss:sp' 
define integer i 
define wordj 

Note that the values of the memory type variables i and j are not saved. 

The following PUT command: 

put defs2.mac lit, def, integer 

places the following text into the file DEFS2.MAC: 

define literally lit = 'literally' 
define literally def = 'define' 
define integer i 

Note that in this example, lit is not expanded to literally when it appears in the 
PUT command. PSCOPE treats lit as the name of a debug object that happens to 
be a LITERALLY. The same is true for the REMOVE command and, in fact, for 
all commands that let you specify a debug object by name. 
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PSCOPE lets you define debug procedures to expand the debugger command lan- 
guage and to aid development of the program you are debugging. Debug proce- 
dures are one of PSCOPE’s most powerful features. 

You can use debug procedures (whose type is PROC) to automate the software 
test process, set up breakpoints based on data values or Boolean conditions, and 
put together complex commands using PSCOPE’s command language. Debug 
procedures let you use parameters (LITERALLYS do not). 

This chapter explains debug procedures basics: how to define them, return values 
from them, make calls to them, and remove them. 


Define Debug Procedure 

The DEFINE command defines a debug procedure. 

Syntax 

DEFINE PROC name = command 
Where: 

name is any name except a reserved keyword. The name can be up to 
254 characters long, of which the first 40 must be a unique 
combination. 

command is a PSCOPE command. 


Description 

A debug procedure contains a single PSCOPE command. This command is usually 
a DO construct, which allows multiple commands and the declaration of local 
variables. 

A debug procedure does not execute when it is defined, only when it is called. 
PSCOPE checks syntax when you define the debug procedure. However, if you 
define a debug procedure within another debug procedure, PSCOPE does not 
define the inner debug procedure until the enclosing debug procedure is called. 
Note that while you can define a debug procedure within another debug 
procedure, all debug procedures are global. 

PSCOPE determines the types of all objects in the debug procedure when you 
define the debug procedure. Changing the type and the definition (or the type or 
the definition) of an object referenced in a debug procedure before you execute it 
can cause errors when you run the debug procedure. 

Referencing actual and formal parameters when you execute a debug procedure is 
described later in this chapter. 
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Debug Procedure Calls 

You can call debug procedures using the syntax shown in the following section. 

Syntax 

name [{expr[,expr]*)] 

Where: 

name is the name of the debug procedure. 

expr is any expression yielding a numeric or string value that is to be 
passed as an actual parameter in the debug procedure. 


Description 

PSCOPE executes the command specified in the debug procedure definition. 
PSCOPE substitutes the values of expr for the actual parameter specifier during 
the execution of the command. 

You can call a debug procedure in the following three ways: 

• In response to a PSCOPE prompt. 

® As an operand of an expression. 

• Upon reaching a breakpoint or tracepoint that uses the CALL option (as ex- 
plained in Chapter 11). 


Debug Procedure Return 

You can return a value from a debug procedure by placing the RETURN command 
in the debug procedure. 


Syntax 

RETURN [expr] 

Where: 

expr is any expression. 

Description 

PSCOPE returns the null value if you do not specify expr This can cause a type 
conversion error if you use the debug procedure as a function. 

PSCOPE displays the expr value if you use a RETURN command outside a debug 
procedure. PSCOPE displays an error message if it expects a return value (such as 
when the debug procedure is used in an expression) but no RETURN is executed. 
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Return values are required from debug procedures used as operands in expressions 
or automatically called upon reaching a breakpoint or a tracepoint (but not from 
debug procedures called in response to a PSCOPE prompt) . 


Accessing Debug Procedure Parameters 

You can reference the values of the parameters passed to the debug procedure 
when it executes. 


Syntax 

% parameter 
Where; 

parameter is one of the following: 


integer-constant is an arbitrary unsigned integer constant specifying 



which parameter you desire. Note that %0 specifies 
the first parameter in the list of parameters passed 
to the debug procedure, %1 specifies the second 
parameter in the list, and so forth. 

iexpr) 

is an expression that specifies the desired 
parameter. 

NP 

is the total number of parameters in the parameter 
list passed to the debug procedure. PSCOPE does 
not limit the number of parameters that you can 
pass to a debug procedure. 


Description 

All parameters are passed by value and are local to the specific execution of the 
debug procedure to which they are passed. Thus, you can call debug procedures 
recursively. 

A debug procedure cannot assign new values to the parameters passed to it. 

PSCOPE displays error messages if you try to access non-existent parameters or 
try to access parameters when no debug procedure is executing. 


Example 

The following debug procedure executes a recursive factorial function: 

« define proc factorial = do 

■ »if %0 < 2 then return 1 

. . «else return %0 * factorial(%0 - 1 ) 

■ - «endif 
. xend 

»factorial(5) 

120 
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The following debug procedure returns the sum of all the parameters passed to it; 


«define proc sum = do 

• ^define longint n = 0 

• ^define integer i = 0 

• * count %np 

■ • *n = n + %(i) 

. . *i = i + 1 
• • »endcount 
. ^return n 

• »end 

»sum(1 ,2,3,4) 

+ 10 

«sum(factorial(3), factorial(4)) 

+ 30 

The following debug procedure lets you trace a byte value every time it is modified 
in a program; 

• define proc trace-byte = do 

• * define byte current-value = byte %0 

• * write 'value =', current-value 
. * repeat until $ == %1 

• . * Istep 

. . * if current-value < > byte %0 then 
...» current-value = byte %0 
. . .* eval $ line 

...» write 'value =', current-value 
...» endif 
. . * endrepeat 

• * eval $ line 
. * end 

» trace-byte (.c, get-iine) 

value = 32 
;DC# 
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This chapter shows you how to define, display, and remove code patches from 
your program. 

This chapter describes the following commands: 

Define patch 
Display patch 
Remove patch 


Defining a Patch 

The DEFINE command is used to create a PATCH. 


Syntax 


DEFINE PATCH addr1 [TIL addr2] = patch-value 
Where: 


addrl and addr2 are expressions which evaluate to a program location 
(e.g., line, procedure, or label reference, preceded by a 
module name if necessary) . 


patch-value is one of the following: 

command is any PSCOPE command, except LOAD, GO, LSTEP, 
or PSTEP. Use a compound construct (see Chapter 6) to 
specify more than one command. 


NOP is a special command which implies that no operation is 

to be performed in the patch. When used with TIL addr2, 
NOP allows statements in your program to be effectively 
deleted. 


Description 

A PSCOPE patch is a PSCOPE command that is executed prior to a statement in 
your program or instead of a sequence of statements in your program. Like all 
other PSCOPE commands, patches are interpreted (rather than translated). 

Patches are active as soon as you define them and remain active until you remove 
them. Note that the LOAD command implicitly removes them. 

You are allowed only one patch per address; PSCOPE will replace the first patch if 
you specify a second patch. 

If you specify only addrl, then program execution resumes at addrl. If you specify 
both addrl and addrl, then program execution resumes at addrl. In either case the 
patch may have changed the execution point (by reassigning $ or CS;IP) , in which 
case execution resumes at the reassigned location. 
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PSCOPE executes patches after it handles any breaks or traces at the same 
location. (Chapter 12 discusses the break and trace commands.) 

PSCOPE executes command (or NOP) upon reaching but before executing addrl. 

Be careful not to overlap patches. For example, because the following: 

DEFINE PATCH #10 TIL #15 

and the following: 

DEFINE PATCH #13 TIL #18 

overlap, PSCOPE ignores part of the second patch. The first patch skips lines 10 
through 14 and resumes at line 15; PSCOPE will not see the patch at line 13. 

You can stop program execution and set the execution point to the location where 
the patch exists by pressing CNTL-C while executing the patch. 

Example 

The following patch inserts a command before statement 10: 
define patch #10 = write 'x = ',x 
The following patch skips statement 15: 
define patch 15 til 16 = NOP 


Displaying a Patch 

This section shows you how to display patches. 

Syntax 

PATCH addrl 
Where: 

addrl is an expression that evaluates to a location in your program that is 
the beginning of a patch. 


Description 

PSCOPE displays the patch that begins at addrl. 

Since addr is an expression, you can use any other expression which evaluates to 
the same program location to reference a patch. However, do not use a symbol 
whose name is a constant but whose value changes (e.g., $) as a patch name. 
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Example 

The following example displays a patch in the sample program DC (found in Ap- 
pendix E): 


^define patch #41 = write 'enter getJine' 
«patch #41 

define patch #41 = write 'enter getJine' 


Removing a Patch 

You can delete patches with the REMOVE command. 


Syntax 

REMOVE PATCH [addi] 
Where; 


addr is the location of the patch you want to remove. 


Description 

The REMOVE command lets you delete the patch at addr. If you do not specify 
addr, PSCOPE deletes all patches. PSCOPE displays an error message if you try to 
remove a patch which you have not defined. 

This syntax is required regardless of which form of the DEFINE command you 
used to define the patch. 


Exampie 

The following example removes the patch at line (or statement) 10: 

«remove patch #1 0 
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CHAPTER 10 
UTILITY COMMANDS AND 
STRING FUNCTIONS 


PSCOPE furnishes a variety of utility commands. This chapter discusses these 
commands, which include the following: 

• EXIT 

• DIR 

• CALLSTACK 

• HELP 

• LIST/NOLIST 

• INCLUDE 

• EVAL 

• BASE 

• INPUTMODE 

• WRITE 

This chapter also describes the following PSCOPE built-in functions: 

• SUBSTR 

• CONCAT 

• STRLEN 

• Cl 

• SELECTORSOF 

• OFFSETSOF 

The EXIT Command 

The EXIT command ends the debugging session. 

Syntax 

EXIT 

The EXIT command has no arguments. 

Description 

The EXIT command automatically closes all open files, prints a termination 
message, and returns you to the host operating system. 
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Example 

The following example illustrates using the EXIT command. 

*exit /* User ends debug session */ 

PSCOPE terminated /* PSCOPE prints termination message */ 


The D I Rectory Command 

The DIR command displays the names of all objects of a specified type that are 
found in a specified set of symbols. The set of symbols can be either program sym- 
bols or debug symbols. 


Syntax 

DIR [director^ Itype] 

Where: 

directory is one of the following: 

DEBUG specifies that the symbols PSCOPE displays come 

from the set of debug symbols (those that were creat- 
ed with the DEFINE command). 

PUBLIC specifies that the symbols PSCOPE displays are those 

found in the user program and that only those sym- 
bols with the PUBLIC attribute are to be listed. 

module-name specifies that the program symbol table (as opposed 
to the debug symbol table) is to be used for the direc- 
tory and that symbols in only the specified module 
are to be listed. 

type is any type (memory, debug, or user). PSCOPE lists only objects 
of the specified type. 


Description 

The DIR command displays the names and types of the set of objects that 
PSCOPE recognizes. You can list either program symbols or debug symbols with 
the DIR command. 

PSCOPE lists all symbols from the specified directory if you do not specify type. 

If you do not specify directory^ PSCOPE uses the current module of the user 
program, unless implies that PSCOPE uses the debug directory. 


Example 

Suppose that you entered the following commands: 

define literally lit = 'literally' 
define lit def = 'define' 
load dc.86 
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The following command lists all debug symbols: 

*dir debug 

DEF literally 

LIT literally 

The following command lists all symbols in the module DC. The indentation 
within some of the procedures indicates local symbol definitions; 


«dir :dc 
DIRof :DC 

PQ_OUTPUT 

PQJNPUT 

@1000 

@9999 

T 

C 

BUFFER 

VARIABLE_TABLE . . . 

ERROR 

E 

GET-LINE 

GET-TOKEN 

DIGIT 

C 

UPPER-CASE .. 

C 

LOWER-CASE . . 

C 

GET-CHAR .... 

FACTOR 

FACTORVALUE 

EXPRESSION-VALUE 
VARIABLE-INDEX . . 

TERM 

TERM-VALUE 

FACTOR-1-VALUE . . 
FACTOR-2-VALUE . . 

OP 

EXPRESSION 

EXPRESSION-VALUE 
TERM-1-VALUE .... 
TERM-2-VALUE .... 

OP 

STATEMENT 

EXPRESSION-VALUE 


... TEXT (file) 

. . . TEXT (file) 

. . . label 
... label 

... TOKEN (record) 

. . . char 

. . . TEXT-BUFFER (record) 

... array of integer 
. . . procedure 

. . . ERROR-CLASS (enumeration) 
. . . procedure 
. . . procedure 

procedure 

char 

. . . procedure 

char 

. . . procedure 

char 

. . . procedure 

procedure 

integer 

integer 

char 

procedure 

integer 

integer 

integer 

char 

procedure 

integer 

integer 

integer 

char 

procedure 

integer 


In the following example, PSCOPE assumes module DC because the user did not 
specify a module. Note that additional qualification indicates local (not module 
level) symbols. 
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»dir procedure 

DIRof :DC 

ERROR 

GET_LINE 

GET_TOKEN 

GET-TOKEN.DIGIT 

GET_TOKEN.UPPER_CASE 

GET_TOKEN.LOWER_CASE 

GET_TOKEN.GET_CHAR 

FACTOR 

TERM 

EXPRESSION 

STATEMENT 


In the following example, the user does not specify a module, but the type speci- 
fied is a debug type. Hence, PSCOPE uses the debug symbol table for the 
directory: 


»dir literally 

DEF 

LIT 


The CALLSTACK Command 


The CALLSTACK command displays your program's dynamic calling sequence. 


Syntax 

CALLSTACKin] 

Where: 

n is an optional integer expression that indicates how much of the call 
stack you want to see. 


Description 

Using the CALLSTACK command, you can symbolically display the current 
chain of procedure calls in your program. In response to this command, PSCOPE 
prints a sequence of fully qualified references to procedures, one per line. The 
reference listed first is the point to which execution control will return when the 
current procedure returns (its return address). The second entry is the return ad- 
dress for the procedure that called the current procedure, and so on. 

The optional expression n indicates how much of the call stack you want PSCOPE 
to display. PSCOPE displays the entire call stack if you do not specify n. A positive 
n value indicates that the first n entries are to be displayed (the mnost recent proce- 
dure calls) . A negative n value indicates that the bottom n entries of the call stack 
are to be displayed (the Meast recent procedures). 

Note that the CALLSTACK command works only when the current execution 
point is inside a module for which PSCOPE has symbol information. 

Example 

The following example illustrates using the CALLSTACK command. 
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«load dc.86 
«go til get_char 
[Break at geLchar] 
»calistack 

:DC.GET_TOKEN +323 
:DC.FACTOR + 156 
:DC.TERM + 15 
:DC.EXPRESSION + 37 
:DC.STATEMENT + 15 
:DC +1787 


NOTE 

The CALLSTACK command does not operate correctly if the 
nesting sequence includes a procedure written in assembly 
language. 

The CALLSTACK command does not operate correctly if the last 
executable statement of the main module calls a procedure. The 
top-level return address must not be within a procedure. 


The HELP Command 

The HELP command displays explanatory text about various topics, including 
PSCOPE commands and extended messages for those errors whose primary error 
message ends with [»] . 

Syntax 

HELP [topic] 

Where: 

topic is one of of the following; 

topic-name is the topic name for which you want help information. 

En is the error number for which you want the extended 

error message. Note that the form En is used even for 
warnings. 

Description 

If you do not specify topic, PSCOPE lists all topics for which help is available. 


Example 

The following example shows how the HELP command is used to get information 
about the BASE command. 

»help base 
BASE 

... (The help information is printed here.) 
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The following example shows what happens when you request HELP on a topic 
for which there is no HELP information. 

*help problem 


PROBLEM 


<sorry, but no help is available> 


The LIST and NOLIST Commands 

The LIST command puts all of PSCOPE terminal output into the specified file, 
and NOLIST closes the file. 


Syntax 

LIST [file-name] 

NOLIST 

Where: 

file-name is the name of the file into which all PSCOPE terminal output 
is placed. 


Description 

The LIST command sends all PSCOPE output to the specified file. If you do not 
specify file-name, PSCOPE displays the name of the currently selected LIST file. 

NOLIST closes the currently active LIST file (if any). Changing the LIST file 
closes the old LIST file. 

Note that PSCOPE sends only PSCOPE terminal output to the file. PSCOPE does 
not send any terminal output printed by a user program to the LIST file. 


Exampie 

The following example uses the LIST and the NOLIST command. 

«list exampl.log 
«iist 

exampl.log 
« nolist 


The INCLUDE Command 

The INCLUDE command gets input from a file. 
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Syntax 

INCLUDE file-name [NOLIST] 

Where: 

file-name is the name of the file from which input is to be taken. 

NOLIST suppresses echoing of the selected file's input on the screen. 

Description 

The INCLUDE command takes input from file-name until it reaches the end of 
the file, at which point input continues from the previous source. 

INCLUDE commands may be nested. The level of nesting depends upon available 
memory. 

You can enter INCLUDE commands from the terminal; they must be the last 
command on a line. 

Depending on the severity of the error, an error in the INCLUDE file returns exe- 
cution to the next command or to the standard command level. 


Example 

The following example illustrates using the INCLUDE command. 

^include regsdnc 

« include file2 nolist /* Suppress printing of contents */ 


The EVAL Command 

The EVAL command has two forms. The first form evaluates expressions and 
prints the results. The second form displays program locations symbolically. 


Syntax 

EVAL expr leval-type] 
Where: 


expr is the expression to be evaluated. 

eval-type is one of the following three optional evaluation types: 


LINE 

PROCEDURE 
SYMBOL 
SYMBOL ALL 


indicates line number 
indicates procedure name 
indicates a fully-qualified reference 
indicates all symbolic variables referenced by 
a particular address 
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Description 

EVAL prints the results of the expression according to the indicated eval-type. 
EVAL can evaluate an expression in different bases or as a program symbol or line 
number. 


If you do not specify eval-type, the value of expr \s printed in the following manner, 
depending upon its type; 

Type Form of EVAL Display 


BYTE All 3 bases (binary, decimal, hex) and ASCII 

BOOLEAN 

WORD 

ADDRESS 

SHORTINT 

INTEGER 

LONGINT 

SELECTOR 

DWORD 


POINTER seg:off (hex) and 20-bit normalized address 

REAL Hexadecimal bytes 

LONGREAL 

TEMPREAL 

EXTINT 

BCD 


CHAR 

Note that PSCOPE prints non-printing ASCII characters as a dot (.). 

If you specify eval-type, PSCOPE tries to find a program symbol whose address is 
equal to the value obtained by evaluating the expression. 

If eval-type is LINE, then PSCOPE displays the following: 

■.module-name # line-number [-i- offset] 


Where: 

module-name is the name of the module in which the address occurs. 

tine-number is the nearest line number in that module-name to that 
address. 

offset is the amount by which the address exceeds the exact ad- 

dress of line-number. 

If eval-type is PROCEDURE, then the next message is displayed: 
:module-name[.procedure-name]* [-1- offset] 

Where: 

module-name is the name of the module in which the address occurs. 

procedure-name is the name of the procedure with the closest match to the 
address. 
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offset is the amount by which the address exceeds the exact ad- 

dress of the procedure-name. 

If eml- type is SYMBOL, then the next message is displayed: 
fully-qualified-reference [+ offset] 

Where: 

fully-qualified-reference is a fully qualified reference, such as 

ds:token_l.m. 

offset is the amount by which the address exceeds 

the exact address of fully-qualified-reference. 


Example 

The following example uses the EVAL command. 

«eval $ procedure 
«eval $ 

»eval ds:1 4h symbol 

If eval-typeis SYMBOL ALL, PSCOPE displays all symbolic variables whose start- 
ing address is expr, that is, PSCOPE supports the FORTRAN EQUIVALENCE 
and COMMON statements and the PL/M AT attribute. For example, if expr is the 
address of more than one program variable, PSCOPE displays all variables stored 
at that location. 

The BASE Command 

The BASE command establishes the default base for numeric constants during 
input and output. 


Syntax 

BASE [= expr] 

Where: 

expr is an expression that evaluates to 2, 10, or 1 6 (decimal) . 


Description 

PSCOPE displays the current radix. When the current base is hexadecimal, 
PSCOPE displays HEX. When the current base is decimal, PSCOPE displays 
DECIMAL. When the current base is binary, PSCOPE displays BINARY. 

You can change the current radix by setting BASE equal to 2T, lOT, or 16T as 
shown in the following example. 

«BASE=1 OH /*Setting the current radix to hex.*/ 

*BASE=1 6T /* Another way of setting the current radix to hex.*/ 

*BASE=1 OOOOY /*Another way of setting the current radix to hex.*/ 

*BASE 

HEX 
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The initial default base is decimal. During input, you can override the default base 
by putting an explicit base suffix on the constant (for example, 12t) . 

Note that PSCOPE command processing goes through the following two steps: 

• Scanning for syntax errors and deciding what to do. 

• Executing the command. 

PSCOPE evaluates numeric constants during the first phase of command 
processing. PSCOPE assigns values to variables during the second phase. Thus, 
commands such as the following: 

«base = lOt 

*base = 16; VAR1 =10 

will give VARl the value 10 (decimal), not 16 (decimal), because PSCOPE scans 
the entire second command line before either of the two commands in the com- 
mand line are executed. Thus, the numeric constant 10, in the second command 
line, is interpreted as 10 (decimal). If you want VARl interpreted as 16 (decimal), 
put the expression VARl = 10 on a separate line, as shown below: 

*base = 10t 
*base = 16 
»YAR1 =10 


ExaitipS6 

The following examples use the BASE command. 

«base = 16t 
«base = OA 


INPUTMODE 

With the INPUTMODE pseudo-variable, you inform PSCOPE what DQ$SPE- 
CIAL mode the program being debugged is using. The DQ$SPECIAL mode deter- 
mines how the operating system interprets console input. 


Syntax 

INPUTMODE[=n] 

Where: 

n is an expression resolving to IT, 2T, or 3T. 


Default 

2 
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Description 


INPUTMODE informs PSCOPE what DQSSPECIAL mode the program being 
debugged uses. PSCOPE uses mode 1. Whenever your program reaches a 
breakpoint, PSCOPE sets DQSSPECIAL to 1 before delivering the prompt. When 
your program resumes executing (you enter a GO command or a STEP 
command) , PSCOPE sets DQSSPECIAL to the value specified by INPUTMODE. 

You need to be aware of this if your program sets the DQSSPECIAL mode to 
other than the current setting of INPUTMODE. If you break and then resume pro- 
gram execution, your program may be resuming with a different DQSSPECIAL 
mode than what you intended. 

DQSSPECIAL is a UDI system call that determines how another UDI system call, 
the DQSREAD, handles input from the console keyboard. 

Input comes from the console keyboard into a system buffer. The DQSREAD 
transfers the input from the system buffer to a user buffer specified as a 
DQSR.EAD parameter. There are three DQSSPECIAL modes, called 1, 2, and 3. 
The default is 2, line-editing mode. The following describes modes 1, 2, and 3. 

1 Transparent 1 mode. Sometimes this mode is just referred to as transparent 
mode. 

The DQSREAD specifies a number of characters. When the system buffer 
contains that number, the DQSREAD transfers those characters to the user 
buffer. If the system buffer already contains the specified number of 
characters, the DQSREAD transfers them immediately, and the user pro- 
gram continues. Otherwise, the DQSREAD waits until the system buffer 
gains the specified number of characters. 

The DQSREAD transfers the characters exactly as you type them. All charac- 
ters (except CNTL-D and CNTL-C) go into the user buffer. These characters 
are not echoed to the screen. 

2 Line-editing 2 mode. This mode is the default. The operating system allows 
editing of the console input line. A line terminates with a carriage return. 
Once you enter the carriage return, you lose the ability to edit that line. The 
operating system interprets and removes all editing characters (such as 
backspace) from the input line and adds a linefeed to the final carriage return 
if the buffer has enough room. 

If the system buffer already contains an edited line, the DQSREAD transfers 
it immediately, and the user program continues. Otherwise, the DQSREAD 
waits until the system buffer obtains a carriage return and completes the line 
editing. 

3 Transparent 3 mode. This mode is sometimes called flush mode and some- 
times called polling mode. 

The DQSREAD transfers whatever characters are in the system buffer to the 
user buffer. If the system buffer contains no characters, no characters are 
transferred. The DQSREAD does not wait for the system buffer to obtain 
any characters. 

The DQSREAD transfers the characters exactly as you type them. All charac- 
ters (except CNTL-D and CNTL-C) go into the user buffer. These characters 
are not echoed to the screen. 
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Example 

Set INPUTMODE to 1 and display it as follows. 

«INPUTMODE=1 

»INPUTMODE 

1 

Because INPUTMODE is a pseudo- variable, you can use it in a debug procedure. 
For example, the following debug procedure displays yes on the console if INPUT- 
MODE is I and no otherwise. 


^DEFINE PROC checkinput=DO 
. *IF INPUTMODE==1 THEN WRITE yes' 
■ « ELSE WRITE 'no' 

. .«ENDIF 
• «END 
»checkinput 
no 


The WRITE Command 

The WRITE command lets you display and format information at the terminal. 

Syntax 

WRITE [USING ('[radix,] formai-item [, [radix,] format-item]*')] list 
Where: 

USING lets you control output using a format string. 
radix is one of the following: 

H Set WRITE command display base to hexadecimal. 

T Set WRITE command display base to decimal. 

Y Set WRITE command display base to binary. 

format’item is one of the following: 

n Decimal number specifying the width of the output field. 
PSCOPE determines the format of the field by the type of the 
expression in the argument corresponding to this format item. 
If n = 0, then PSCOPE uses the normal display length of the 
item without padding or truncation for the width of the output 
field. 

nC Move output buffer to column n (first column is 1) . 
nX Skip n spaces in the output buffer. 

Terminates the format string (optional) . 
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> Terminates the format string and specifies that no carriage 
return or line feed is to be issued following the WRITE 
command. 

& Terminates the format string and specifies that the write 
output buffer is not to be flushed at the end of this WRITE 
command but is to be added to by later WRITE commands. 

"text" Puts the text between the quotation marks (") into the output 
buffer. 

list uses the following syntax: 

name .name * 

expression .expression 

string-spec _.string-spe^ 


Where: 

string-spec is an expression that evaluates to a string. 

expression is an expression whose value you want to display at the 
terminal. 


Description 

The WRITE command displays the items in its argument list at your terminal. 

In its simplest form, the WRITE command lets you print a list of expressions. 
PSCOPE prints the value to be printed according to the current output base. 


The USING option lets you control output using a format string consisting of 
format items separated by commas. If you use a format item for one variable, then 
you must use a format item for each variable in list. When text is the only format 
item, you must use a terminator (., > , or $) . 


Example 

The following example uses the WRITE command. 

«write 'hello' 
hello 

^define byte b = 5 
»write using ("'b =",0') b 
b = 5 


The String Functions (SUBSTR, CONCAT, 

STRLEN, and Cl) 

PSCOPE provides three string manipulation commands: SUBSTR, CONCAT, and 
STRLEN. In addition, the Cl function lets you enter a single character string from 
the keyboard. 
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Syntax 

SUBSTR (string-spec, start, length) 

CONGAT (string-spec [, string-spec]*) 

STRLEN (string-spec) 

Cl 

Where: 

string-spec is an expression that evaluates to a CHAR value. 
start and length are expressions that evaluate to integer values. 


Description 


The SUBSTR function returns the specified substring starting at startand of length 
length. The first character of a string is in position 1. PSCOPE returns the null 
string if arguments do not make sense (for example, negative length, start past 
end of string, etc.) . If start is valid but length goes beyond the end of the string, 
PSCOPE returns the rest of the string beginning at start. 

The CONCAT function creates a new string by concatenating specified string-specs. 
You can implicitly concatenate string constants (as described in Chapter 3) . 

The STRLEN function returns the length of its argument string. The length of the 
null string is zero. You can use the STRLEN function anywhere a number is valid. 

The Cl function reads one character from the keyboard and returns a string of 
length one having that character as its value. When Cl is referenced in an 
expression, execution pauses until you enter a character. PSCOPE does not display 
the entered character on the terminal screen. 


Example 

The following examples use the CONCAT, SUBSTR, and the STRLEN 
commands. 

^define char ch1 = 'The' 

^define char ch2 = ' quick' 

« define char ch3 = ' brown' 

* define char ch4 = ' fox' 

«concat (chi ,ch2,ch3,ch4) 

The quick brown fox 

»SUBSTR (ch3, 3, 3) 
row 

«STRLEN (CONCAT(ch1,ch4)) 

7 
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The following example assumes that the character z is entered when execution 
pauses during the execution of the command: 

«if ci - 'z' then write 'sleepy?' 

,«endif 

sleepy? 

The SELECTORSOF and OFFSET$OF Functions 

PSCOPE provides two functions for extracting the selector (or segment) and 
offset portions of a pointer value. 

Syntax 

SELECTOR$OF (expr) 

OFFSET$OF (expr) 

Where: 

expr is an expression that evaluates to a pointer value. 


Description 

SELECTOR$OF returns the selector (or segment) portion of a pointer value. 
OFFSETSOF returns the offset portion of a pointer value. 

The dollar sign ($) in the names of these functions is optional (as in all PSCOPE 
names) and is included here to improve readability. 

Note that these functions correspond to the PL/M V2.0 functions with the same 
names. 

Example 

The following examples use the SELECTORSOF and the OFFSETSOF functions. 

*base = 16t 

^define pointer p = 1 23:456 

*p 

0123H:0456H 

»selector$of(p) 

123 

«offset$of(p) 

456 
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CHAPTER 1 1 
ADVANCED EXECUTION AND 
TRACE COMMANDS 


This chapter explains how to control and trace program execution. It describes the 
break and trace registers, as well as how to load and use them. Automatic calling of 
debug procedures, conditional break and trace, and the break/trace/patch table are 
covered as well. 


Breaking and Tracing 

Using procedures, labels, and statements, PSCOPE’s breaking and tracing com- 
mands let you control and monitor the execution of the program you are 
debugging. 

Breaking and tracing makes use of debugger objects called break registers 
(BRKREGs) and trace registers (TRCREGs). Breakpoints and tracepoints are 
defined and stored in these registers and activated with the GO command. 


Break Registers (BRKREG) 

Break registers are named registers that can hold any number of breakpoints. You 
can define any number of break registers within PSCOPE’s workspace limits. 

Placing breakpoints in a named break register lets you easily switch active break- 
points while maintaining control of program execution. 

PSCOPE lets you break upon reaching a particular program location, which can be 
referenced symbolically as a line number, label, or procedure (see Chapters 3 and 
5) or as an actual address. In the latter case, PSCOPE assumes that the user en- 
tered a valid break location. This location must be on an instruction boundary. 

A break occurs when PSCOPE reaches a specified location and before execution of 
the statement at that location. If you set a breakpoint at a procedure, PSCOPE 
stops execution at the prologue of the procedure, before processing the declara- 
tions for the procedure and before the first executable statement of the procedure. 

Since BRKREG is a debug type, the standard debug object manipulation com- 
mands described in Chapter 7 apply to BRKREGs. Also, you must enter the value 
in the definition; it must be a list of location references (line numbers, labels, 
procedures, or actual addresses) separated by commas as specified in the following 
syntax section. 

The address you specify in a break register can be the address of a high-level lan- 
guage statement or an assembly language instruction. 


Syntax 

DEFINE BRKREG name = break-item [, break-item]* 
Where: 


name 


is the name of the break register. 
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break-item is one of the following: 

breaks [CALL proc-name] 
breaks is one of the following: 

break-ptl break-pf\* 

break-pt can be any expression that evaluates to a location in 
your program. 

proc-name is the name of a debug procedure that returns a value. 

Description 

You can create a break register with a specified name that contains all the listed 
break-pfs as its breakpoints. Note that PSCOPE associates the breakpoints only 
with their defined break register. Breakpoints are not active until you specify their 
break register in a GO command. (The GO command is discussed later in this 
chapter.) 

If you specify the CALL option, PSCOPE associates proc-name the single or 
parenthesized list of break-pfs^XQCQdmg it. 

Note that you cannot modify break registers with a PSCOPE modify command; 
you must redefine break registers. However, you can add or delete breakpoints 
from an existing break register by editing the BRKREG definition with PSCOPE’s 
interna! editor (discussed in Chapter 2). 

After you activate a break register with the GO command, program execution pro- 
ceeds until PSCOPE encounters one of the breakpoints contained in that register 
(i.e., program execution reaches that point). Then PSCOPE stops program execu- 
tion and displays a breakpoint message. If a debug procedure is associated with the 
breakpoint, PSCOPE automatically executes the debug procedure. PSCOPE con- 
verts the return value from the debug procedure to a Boolean. If the Boolean value 
is TRUE, PSCOPE breaks and displays a break message, as if it had not called the 
debug procedure. If the Boolean value is FALSE, PSCOPE continues execution 
without interruption, as if no breakpoint was there. If there is no return value, 
PSCOPE detects an error and stops execution. This feature lets you set conditional 
breakpoints with the decision to break based on any Boolean condition, including 
program variable values or terminal input (see the Cl command in Chapter 10). 
Note that PSCOPE does not allow parameters on the debug procedure specified in 
the CALL option. 


Break messages have the following form: 

[Break at break-pt] 

Where: 

break-pt is the location you specified in the definition of the break register. 

Example 

Note that all the following examples use the sample program DC (shown in Ap- 
pendix E) . 
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The following example defines one break register containing four breakpoints, 
each at a different procedure in DC: 

* Define Brkreg break-1 = error, statement, term, factor 

This break register has one breakpoint, which calls a debug procedure: 

« Define Brkreg input-check = get-iine CALL PROC2 

The following example defines a break register with four breakpoints, two of 
which call the debug procedure PRl : 

^Define Brkreg special = (term, value) CALL PRl , 

** :dc#68, :dc + 1741 

Trace Registers (TRCREG) 

Trace registers (TRCREG) are (defined and operate almost exactly like break regis- 
ters (BRKREG). The only difference is that the tracepoints contained in trace 
registers do not stop program execution; they display trace messages instead. 

Trace registers are named registers that can hold any number of tracepoints. You 
can define any number of trace registers within PSCOPE’s workspace limits. 

Putting tracepoints into a named trace register lets you easily switch active trace- 
points while maintaining control of program execution. 

PSCOPE lets you trace upon reaching a particular program statement, label, or 
procedure. 

The trace occurs when PSCOPE reaches a specified location and before execution 
of the statement at that location. Tracing a procedure stops execution at the prol- 
ogue of the procedure, before the declarations in the procedure are processed and 
before the procedure’s first executable statement. 

Since TRCREG is a debug type, the standard debug object manipulation com- 
mands described in Chapter 7 apply to TRCREGs. Also, you must enter the value 
in the definition; it must be a list of location references (line numbers, labels, 
procedures, or actual addresses) separated by commas as specified in the following 
syntax section. 

Syntax 

DEFINE TRCREG name= trace-item [, trace-item]* 

Where: 

trace-item is one of the following: 

traces [CALL proc-name] 
traces is one of the following: 

trace-pt[, trace-pt]* 

trace-pt can be any expression that evaluates to a location 
within the user program. 

proc-name is the name of a debug procedure that returns a value. 
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Description 

You can create a trace register with a specified name that contains all the listed 
trace-pfs as its tracepoints. Note that PSCOPE associates the tracepoints only with 
their defined trace register. Tracepoints are not active until you specify the trace 
register in a GO command. (The GO command is discussed later in this chapter.) 

If you specify the CALL option, PSCOPE associates proc-name with the single 
trace-ptoi parenthesized list of preceding it. 

Note that you cannot modify trace registers with a PSCOPE modify command; you 
must redefine trace registers. However, you can add or delete tracepoints from an 
existing trace register by editing the TRCREG definition with PSCOPE’s internal 
editor (discussed in Chapter 2) . 

After you activate a trace register with the GO command, program execution pro- 
ceeds until PSCOPE encounters one of the tracepoints contained in that register 
(i.e., program execution reaches that point). Then PSCOPE displays a trace 
message, and program execution continues. If a debug procedure is associated 
with a tracepoint, PSCOPE automatically executes the debug procedure. PSCOPE 
converts the return value from the debug procedure to a Boolean. If the Boolean 
value is TRUE, PSCOPE displays the trace message, as if the debug procedure was 
called. If the Boolean value is FALSE, PSCOPE continues execution without dis- 
playing a message, as if there was no tracepoint. If there is no return value, 
PSCOPE detects an error but continues program execution. This feature lets you 
set conditional tracepoints with the decision to trace based on any Boolean 
condition, including program variable values or terminal input (see the Cl com- 
mand in Chapter 10). Note that PSCOPE does not allow parameters on the debug 
procedure specified in the CALL option. 

Trace messages have the following format: 

[At trace-pt] 

Where: 

trace-pt is the location specified in the definition of the trace register. 


Example 

Note that all the following examples use the sample program DC (found in Appen- 
dix E) . 


The following example defines a trace register containing three tracepoints: 

^define TRCREG trace_1 = #80, #224, @1000 

The following trace register contains one tracepoint, which calls a debug 
procedure: 

^define trcreg error^check = idc.error CALL write_message 


The GO Command 

The GO command controls user program execution. It also lets you activate any 
number of breakpoints or tracepoints. 
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Syntax 

GO [brk-spec]* 
GO FOREVER 


Where: 

brk-spec is one of the following: 

TIL break-pt [, break-pt]* 

USING reg-ltem [, reg-item]* 
reg-item is one of the following: 

break-register specifies a previously defined break register. 
trace-register specifies a previously defined trace register. 
BRKREG 
TRCREG 


Description 

The GO command starts executing your program from the current execution 
point ($). The LOAD command sets the initial value of $. 

If you specify FOREVER, PSCOPE starts executing without any breakpoints. 
Note that you can use CNTL-C to interrupt execution, but execution may stop in a 
location for which PSCOPE has no symbol information (for example, inside UDI, 
the universal development interface) . 

If you do not specify brk-spec, PSCOPE resumes execution with the same set of 
break and tracepoints that the last GO command used (except for any break regis- 
ters or trace registers that were removed or redefined, in which case they are 
inactive). If you specify USING, PSCOPE starts program execution using the 
breakpoints and tracepoints in the break and trace registers specified. If you specify 
the keywords BRKREG and TRCREG with USING, PSCOPE uses all break regis- 
ters or trace registers. 

If you specify TIL, PSCOPE starts program execution using the points listed. As 
described in Chapter 4, these may be labels, line numbers, procedures, or actual 
addresses (in which case PSCOPE assumes that the user entered a valid break 
address) . 

You can specify any number of TIL and USING clauses. The number of active 
breakpoints and tracepoints is limited only by the amount of PSCOPE workspace 
available. 

You can set both a breakpoint and a tracepoint at the same location but only one of 
each type at the same location. PSCOPE displays a warning message if you try to 
set a breakpoint (or tracepoint) where an active break (trace) point already exists. 
The original breakpoint (tracepoint) remains intact. 

In addition, you can define a patch at a breakpoint and a tracepoint location (or a 
breakpoint or a tracepoint location) . In this case, PSCOPE handles the tracepoint 
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first (including any debug procedures associated with it). PSCOPE next handles 
the breakpoint (including any debug procedures associated with it) and finally the 
patch. However, if PSCOPE stops because of the breakpoint, PSCOPE does not 
execute the patch until the next GO command. 

Breakpoints and tracepoints are active only during execution initiated with the GO 
command. They are automatically deactivated when control returns to PSCOPE. 
Note that breakpoints and tracepoints are not active during stepping with the 
PSTEP and ESTEP commands, while patches are active during stepping. 

Note that PSCOPE deactivates all breakpoints and removes all break registers, 
trace registers, and patches when you invoke the LOAD command. 


Example 

The following example executes break and trace registers: 

GO USING break_l, error_check, input 

The following example reuses the breakpoints and tracepoints activated during the 
previous GO command: 

GO 

The following example activates all trace registers and one breakpoint: 

GO USING trcreg TIL :dc. error 

The following example initiates execution with no break or tracepoints: 

GO FOREVER 

The following sequence of commands illustrates the combined use of break 
registers, trace registers, and breakpoints. The example starts execution and prints 
a trace message every time procedure get_token is called. Execution stops when 
either error or get_line is called: 

DEFINE TRCREG T1 = :dc.get_token 

^DEFINE BRKREG B3 error 
tGO USING T1 , B3 TIL geUine 


Exception Trapping 

PSCOPE automatically traps exception conditions within the user program. The 
exceptions trapped are from UTS, UDI, and the 8087 emulator and include 
DQEXIT. Unlike standard user breakpoints, these exceptions are always active; 
they are created, removed, and replaced only by the LOAD command. 

PSCOPE displays two messages when an exception condition occurs. The first 
message identifies the type of exception. The second message is as follows: 

[Stop at location] 

Where: 

location is the line number or address of the exception handler, not the lo- 
cation within the user program where the exception occurred. 
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A trap at DQ$EXIT lets you inspect variables and continue normal debugging 
when the program has completed its execution. This is a good opportunity to save 
definitions of debugger objects that you want to use in future debug sessions, such 
as patches, debug procedures, and break registers. At this point, you cannot con- 
tinue program execution. A GO command after trapping at DQEXIT causes 
PSCOPE to exit. 
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APPENDIX A 
ERROR MESSAGES 


This appendix lists the PSCOPE error messages. PSCOPE error messages are 
coded by number and listed in numeric order for easy reference. 

Classes of Errors 

Each of the errors detected by PSCOPE falls into one of the following five classes: 

• WARNING. A minor problem which PSCOPE attempts to correct, then 
executes. 

• ERROR. A problem of sufficient severity that PSCOPE aborts the command 
currently executing and either prompts for a new command or retrieves the 
next command from the current INCLUDE file (if any) . 

• SEVERE ERROR. A problem, that may cause difficulties beyond the current 
command. PSCOPE aborts the current command, cancels any pending com- 
mands from INCLUDE files, and prompts for a new command from the 
terminal. 

• FATAL ERROR. A problem from which PSCOPE cannot recover and relia- 
bly continue operating. PSCOPE closes all files, frees all resources that it or 
the program being debugged may have allocated, and returns control to the 
host operating system. (Very few PSCOPE errors are fatal. Do not worry 
about fatal errors aborting a debug session.) 

• INTERNAL ERROR. A violation of one of PSCOPE’s internal consistency 
checks. Please document the situation in which the error occurred and report 
it to your Intel representative. 


HELP 

Some errors have extended error messages. You can reach the extended error 
messages by using the following HELP command: 

HELP En 

Where: 

n is the number of the error message. 

PSCOPE indicates errors that have extended error messages by placing an asterisk 
enclosed in brackets ([*]) at the end of the primary message for that error. 


Error Messages 

0 Type definition record with an unrecognizable format. 

1 Array’s lower bound is unknown - zero is assumed. 

2 Symbol is not an array or the symbol has fewer dimensions than 
specified. 
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3 Size of the array elements is not known. 

4 Referenced array expects a single character array index. 

5 Address of module is not known. 

Tried to reference an assembly language module, a run-time library, 
OS run-time, or a module with no debug information. 

6 Unknown module specified. 

7 No line information was loaded for module. 

8 No symbol information was loaded for module. 

9 Cannot determine module for specified location. [*] 

Could not find specified location in any known module. Specified loca- 
tion is either outside of the program or in a module for which there is 
no symbol information, 

10 Cannot determine current default module. [*] 

Could not find current location in any known module. Either the cur- 
rent execution point is outside of the program or it is in a module for 
which there is no symbol information. 

1 1 Symbol currently not active. [*] 

Symbol is either not known or is not local to the current procedure. 
12. Symbol not known in current context. Change context with the 
NAMESCOPE command or use a fully qualified symbol reference. 

13 No symbol information was loaded for program. 

14 Attempt to reference a program symbol of an unsupported type. 

15 Symbol is not known to be a record and cannot be qualified. 

16 Symbol is not a known record field name. 

17 Cannot determine offset of a field from the start of record. [*]. The 
requested field cannot be referenced because the debugger cannot 
determine the size of one of the preceding record fields. 

1 8 Nested symbolic references not permitted. 

19 Symbol isn’t a pointer variable or its dereference type is unknown. 

20 Specified line is not an executable statement. 

2 1 Specified line does not exist in module. 

22 Cannot evaluate line reference. M 

The segment part of the line reference pointer is not known. Maybe 
the symbol information was not loaded for the module. 

23 Specified type is incompatible with directory, [*] 

Specified type cannot be used with the specified (or default) directory. 
For example, DIR PUBLIC LINE is contradictory, as there are no 
public lines. 

24 Cannot perform symbol table request. No user program loaded. 
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40 Tried to REMOVE debugger object declared locally in DO. .END 
block. 

41 Workspace exceeded. [*] 

Out of workspace. Delete any unnecessary debugger objects (e.g., 
PROCs, LITERALLYs, PATCHes). This can also be caused by 
deeply recursive debug procedures. 

42 The name is either undefined or not of the correct type. 

43 The name is undefined. 

44 The name is already defined with a different type. 

45 Parameter outside the body of a PROC. 

46 The name is not a PROC. 

47 Illegal type specified in DIR DEBUG command. 

48 The named object is not a literally. 

49 Illegal assignment to register. 

50 String too long to perform assignment. 

51 Error in debug symbol lookup. [»] 

May be caused by removing a global debug variable referenced in a 
debug procedure (or patch) and then executing the debug procedure 
(or patch) . 

52 No patch defined at the specified location. 

64 Attempt to PUT or APPEND a local debug object. 

65 I/O error on PUT file. 

66 This command is not currently implemented. 

67 This command not allowed inside of a compound command. 

68 Invalid type. 

69 Invalid type conversion. 

70 String longer than 254 characters. 

71 String too long for numeric conversion. [*] 

Character strings must be of length 1 to convert to unsigned numbers. 

72 Illegal type in output. 

73 Unmatched double quotes in format string. 

74 Write list too long. 

The maximum is 20 items. 

75 Write data too large. 

The maximum is 256 bytes. 
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76 Invalid format string in WRITE command. 

77 Output buffer overflow. 

The limit is 128 characters per line. 

78 Invalid floating point value for output. 

79 Invalid expression for MTYPE. 

An illegal value is being assigned to a memory template. 

80 Invalid boolean operation. 

8 1 Invalid string operation. 

82 Invalid pointer operation. 

83 Invalid unknown operation. 

84 Attempt to assign value to code instead of variable. [*] 

Tried to assign an expression to a location associated with user data 
(e.g., imain.procl == 5, where prod is a procedure in module main). 
Straight assignments may be made only to variables or with memory 
modify commands (e.g., byte 100:200 = 5). 

85 Attempt to assign illegal value to BASE variable. 

86 Cannot use editor if debugger was invoked with SUBMIT control. 

87 Not in a procedure or in a procedure with no debug information. [*] 

In order for the calling procedure to be identified (and the CALL- 
STACK command to function properly), the current execution point 
must be in a procedure or in a procedure for which there is debug 
information. 

88 The debugger has overflowed its 86 stack. [*] 

The debugger has overflowed its stack, probably due to deep recursion 
of a debug procedure. 

89 UDI exception. 

A PSCOPE operation resulted in a UDI exception. A divide-by-zero 
on unsigned values will cause this error. 

90 Literally nesting too deep. 

9 1 Illegal extended integer. 

92 Attempt to assign illegal value to INPUTMODE variable. 

93 Error in VIEW command. 

110 No data segment information. Program may execute incorrectly. [*] 
The load module did not provide any information about the data 
segment. Therefore, execution of the program may have unexpected 
results. 

111 No stack segment information. Program may execute incorrectly. W 
The load module did not provide any information about the stack 
segment. Therefore, execution of the program may have unexpected 
results. 
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112 Program cannot be loaded. [*] 

Program start address needs a fix up by the linker. 

113 The 8087 Emulator was not found in the load module. [*] 

If the E8087 option is specified in the load command, then the 8087 
emulator must be linked into the program being debugged. It was not 
found at load, so it either never existed or it was purged. 

1 14 Missing CH8087 option when loading a program with real math. 

115 Bad object record in load file. 

Verify that you are loading an LTL object file. If there are still bad 
records, relink module. 

116 Load file contains absolute load addresses. [ * ] 

Load file is not PIC or LTL. Relink with the BIND control. 

117 Load file contains unresolved externals. 

Program must be relinked before debugging. 

118 Support for overlays not implemented. 

Loaded program cannot contain overlays. 

119 Memory segment request failure during load. W 

More memory is needed to load the program. Deleting debugger ob- 
jects will not increase available memory for loading. 

120 Load module contained no starting address information. [*] 

The load module did not provide any information about the starting 
address. The load was aborted, and execution of the program is not 
possible. 

136 Divide by zero (operation yields 0 result) . 

137 Invalid type for arithmetic. 

138 Invalid integer operation. 

139 Real math is not available. [*] 

In order to use real math (including any operations or reference to 
real numbers), you must use the E8087 option on the LOAD com- 
mand and have the 8087 emulator linked into the program under 
debug. This error may be detected if the E8087 option was used on 
the LOAD command with a program that appears to have the emula- 
tor linked into it but does not. (This can happen with Pascal and FOR- 
TRAN programs linked with 87NULL.LIB.) 

1 40 Invalid real number. 

141 Attempted real comparison with NAN, + infinity or -infinity. 

142 Invalid real operation. 

1 43 Invalid extended integer operation. 

1 44 Illegal numeric constant. 

160 Attempt to INCLUDE :CL. 

161 I/O error on INCLUDE file. 


A-5 



Error Messages 


PSCOPE-86 User’s Guide 


162 

163 

164 

165 

166 

167 

168 
169 

177 

178 

196-249 

353 

354 

355 


356 

357 

358 

359 

360 

361 


I/O error on LIST file. 

I/O error while loading object file. 

Could not open load file. 

Error while attempting to open virtual symbol table. [*] 

The virtual symbol table uses :WORK: for the disk-resident portion of 
the virtual symbol table. Ensure that the device for :WORK; is ready 
and that PSCOPE has access rights to it. 

Error while attempting to seek in virtual symbol table. 

Error while attempting to write to virtual symbol table. 

Error while attempting to close virtual symbol table. 

Error while attempting to read virtual symbol table. 

First address is greater than second address. 

Attempt to use VIEW command while running PSCOPE under 
SUBMIT. 

Errors 196 through 511 are PSCOPE internal errors. They result from 
consistency check failures and should never occur. If an internal error 
does occur, please notify an Intel representative. 

Illegal number. 

Unrecognized 8086/8087 mnemonic. 

Illegal use of indirect addressing. [*] 

The correct forms of indirect addressing are: 

< symbolic ref> [BX] + offset 

< symbolic ref> [BP] -I- offset 

< symbolic ref> [DI] -t- offset 

< symbolic ref> [SI] -I- offset 

< symbolic ref> [BP] [DI] -f offset 

< symbolic ref > [BP] [SI] -I- offset 

< symbolic ref > [BX] [DI] + offset 

< symbolic ref > [BX] [SI] -1- offset 

The symbolic reference (of the form :MODULE.SYMBOL.SYM 
BOL.etcland the ‘-h offset’ are optional. 

Illegal single line assembler operand. 

Single line assembler syntax error. See HELP SASM. 

Memory pointer (eg. BYTE, WORD, etc) without memory 
operand (eg. number or symbolic reference) . 

Too few operands for this instruction. 

Illegal operands, both operands appear to reference memory. 

The types of the operand (s) do not match the mnemonic or each 
other. 
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362 

512 


513 


514 


515 


528 


529 


530 

531 

532 


One byte relative jump is out of range. Range is -“128 to -h 127. 

The cause of execution break is unknown to PSCOPE. [*] 

PSCOPE cannot determine how execution was broken; it was not 
through a known breakpoint or a CNTL-C. You probably placed an in- 
terrupt at the given address or entered CNTL-D. 

This breakpoint is already active. [»] 

You can activate only one breakpoint of each type (break, trace, or 
patch) at any one address. The break you originally activated is still 
intact. 

Invalid return type from PROC called at breakpoint. [*] 

The debugger procedure called at the breakpoint or tracepoint re- 
turned a value with an invalid type or had no return value. The return 
value must be a BYTE, WORD, DWORD, BOOLEAN, or INTEGER 
(including LONG/SHORT). PSCOPE manufactured a return value of 
TRUE, causing the associated break or trace to be executed. 

There was a patch in progress and it was not completed. [*] 

A code PATCH was being executed when execution was interrupted. 
The current execution point is the standard resume address (the point 
in the program to which control would normally be transferred after 
the patch), as if the PATCH had com_pleted (unless the PATCH 
changed it). The entire PATCH will most likely not have completed 
execution. If the resume address is the PATCH address, then restart- 
ing execution re-executes the patch. 

Attempted recursive definition of a break or trace register. [*] 

Tried to define the named break register or trace register while already 
in the process of defining one. This happens when an expression in 
the definition of a break or trace register calls a debug procedure 
which defines the named break or trace register. 

Cannot determine proper statement address for step. [*] 

Either PSCOPE cannot determine the current execution point and, 
therefore, cannot do statement level stepping, or you tried to start 
statement-level stepping when the current execution point is not the 
beginning of a statement. In the latter case, use the GO command to 
get to a statement, then retry the step. 

No break or trace registers (of the requested type) have been defined. 
This command cannot occur inside of a PATCH. 

No program was loaded. 


544-546 Errors 544 through 546 are PSCOPE internal errors. They result from 
consistency check failures and should never occur. If an internal error 
does occur, please notify an Intel representative. 
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Configuration Commands 


PSCOPE is designed to run on an Intellec Series III or Series IV development 
system. The editor expects code from the terminal or sent to the terminal to be 
code used by Intel terminals. 

You can, however, configure PSCOPE to operate with other terminals. You need 
configuration files when using a non-standard or non-Intel terminal with charac- 
teristics different from those of the Series III or Series IV screen. Configuration 
files let you indicate characteristics of your particular terminal by setting various 
parameters and specifying control sequences by which various screen functions 
can be performed. Configuration files are not needed when using a Series III or 
Series IV with the integrated screen. 

You should put configuration commands in a CRT configuration file (e.g., 
PSCOPE. CRT) so that they are automatically executed when you invoke 
PSCOPE. The configuration commands let you modify certain keyboard and CRT 
codes. In some situations, you may not be able to use certain editing functions. 

To create a PSCOPE configuration file, compare your terminal’s behavior to the 
actions expected by PSCOPE. Refer to your user manual for the codes that your 
terminal expects and generates. (See Table B-1 for a list of the PSCOPE configura- 
tion commands, their default values, and meaning.) 

Note that the CRT configuration commands are compatible with the configuration 
commands accepted by the Series III or a Series IV text editor, AEDIT, in its 
AEDIT.MAC file. (See AEDIT Text Editor User’s Guide, order number 121756.) 

PSCOPE expects the following characteristics in a terminal: 


• ASCII codes 20H through 7EH display some symbol requiring one column 
space. Carriage return (ODH) and line feed (OAH) perform their usual 
functions. 

• There are cursor key output codes and CRT cursor output codes for the fol- 
lowing cursor functions; down, home, left, right, and up. Output codes for 
clear screen, clear rest of screen, clear line, clear rest of line, and direct 
cursor addressing are desirable but not required. You can change default 
codes, shown in Table B-1, with the configuration commands. 

• The terminal accepts a blankout code that blanks out the contents of the 
screen location from which it is entered. You can change the default, 20H, 
with the configuration commands. 

• The CRT has 22 to 25 lines. You can change the default, 25 lines, with the 
configuration commands. 

• PSCOPE automatically generates a line feed each time you enter a carriage 
return. Your terminal should not generate a line feed with a carriage return. 
You can switch this feature on and off on some terminals. 
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When configuring to execute on a non-Intel terminal, you may have to change 
some or all of the codes assigned to the following configuration commands: 

• The cursor key output codes expected by the editor: AFCH, AFCU, AFCD, 
AFCR, and AFCL. 

• The editor-generated cursor movement codes sent to the CRT: AFMH, 
AFMU, AFMD, AFMR, AFML. 

• The erase screen code, AFES. 

• The blankout code, AFBK. 

• The screen size code, AV. 

• The BREAK character code, AB. 

• The codes expected by the editor for the screen mode commands: AFXA, 
AFXF, AFXX, AFXU, and AFXZ. You may want to change these codes to 
match function keys or other convenient keys on the terminal keyboard. 

Table B-1 lists the configuration commands, their default values, and their 
meaning. 

The following conventions apply to Table B-1 : 

• A? must be 22, 23, 24, or 25. 

• /? is a one-byte hexadecimal number. 

• hhhh is a one- to four-byte hexadecimal number. A null value indicates that 
the function is not available. 

• T is 'T' or T', indicating true. 

• F is T' or T I indicating false. 

You must end all commands in the CRT file with a semicolon (;) or a carriage 
return. 


Table B-1 Configuration Commands 


Command 

Series III 
Default 

Meaning 

AV = n 

25 

Sets the number of lines of the display. 

AB = hhhh 

1BH 

Sets ESC. 

AR==hhhh 

7FH 

Sets RUBOUT. 

AFXA = hhhh 

1H 

Sets DELETE RIGHT (CNTL-A) 

AFXF = hhhh 

6H 

Sets CHAR DELETE (CNTL-F) 

AFXX = hhhh 

18H 

Sets DELETE LEFT (CNTL-X) 
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Table B-1 Configuration Commands (continued) 


Command 

Series Ilf 
Default 

Meaning 

AFXZ = hhhh 

1AH 

Sets CLEAR LINE (CNTL-Z) 

AFCD = hhhh 

1CH 

Sets DOWN. 

AFCH = hhhh 

1DH 

Sets HOME. 

AFCL = hhhh 

1FH 

Sets LEFT. 

AFCR = hhhh 

14H 

Sets RIGHT. 

AFCU = hhhh 

1EH 

Sets UP. 

AFIG = h 


This character will be ignored if it is entered. This character 
is needed on terminals, which have multiple character key 
codes for UP and DOWN, such as the Hazeltine 1510. AFIG 
should be set to the lead in (tilde) and UP and DOWN should 
be set to the second letter of the cursor up or down key code. 
This avoids problems caused by the lack of a type-ahead 
buffer. 

AFMB = hhhh 

ODH 

Moves the cursor to the start of the line. 

AFMD = hhhh 

1CH 

Moves the cursor down. 

AFMH = hhhh 

1DH 

Moves the cursor home. 

AFML = hhhh 

1FH 

Moves the cursor left. 

AFMR = hhhh 

14H 

Moves the cursor right. 

AFMU = hhhh 

1EH 

Moves the cursor up. 

AFES = hhhh 

1B45H 

Erases the entire screen. 

AFER = hhhh 

1B4AH 

Erases the rest of the screen. 

AFEK = hhhh 

1B4BH 

Erases the entire line. 

AFEL=hhhh 


Erases the rest of the line. 

AFAC = hhhh 


Addresses the cursor lead-in. When used, the code will be 
followed by a column number (0 to 79) and a row number (0 to 
24). 

AO = h 

OH 

Offset to add both a row and a column number with an ad- 
dress cursor command. 

AX=TorF 

T 

True if X (column) precedes Y (row) in the address cursor 
command. 

AW-TorF 

T 

Allows the user to indicate that the terminal wraps when the 
character Is printed in column 80. 

AFIL = hhhh 


Inserts the line code. Used in line 0 for reverse scrolling. 

AFDL = hhhh 


Deletes the line code. Used to speed up the display on the 
Hazeltine 1 51 0 and similar terminals. 

AFBK-h 

20H 

Blankout character. BLANK on most terminals. 
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Tested Configurations 

This appendix contains tested configurations for several non-Intel terminals. The 
terminals presented here are not the only ones on which you can use PSCOPE; 
they are just the ones that have been tested. The following sections list the configu- 
ration functions and values required to run PSCOPE on the Intel tested terminals. 
The terminals are as follows: 

• ADDS Regent 200 (2400 baud only) 

• ADDS Viewpoint 3A Plus 

• Beehive Mini-Bee 

• DECVT52 

• DECVTIOO 

• Hazeltine 1420 

• Hazeltine 1510 (Tilde lead-in) 

• Hazeltine 1510 (ESC lead-in) 

• Intel Series III E 

• Lear Seigler ADM-3 A 

• Televideo 9 1 0 Plus 

• Televideo 925 and 950 

• Zentec 

The commands to configure PSCOPE for the tested terminals are included on the 
disk with the PSCOPE program. The name of the file is included in each 
description. 

Configuration files for the following terminals can be created by entering the com- 
mands specified in the corresponding tables. 

ADDS Viewpoint 3A Plus 
Hazeltine 1420 
Intel Series HIE 
Televideo 910 Plus 
Televideo 925 and 950 
Zentec 
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ADDS Regent Model 200 

The ADDS model has a 24-!ine CRT display with 80 characters per line. Each char- 
acter is formed in an 8 by 8 dot matrix as a dark character on a light background. 
The 25th line of the screen displays the operating condition of the terminal. Table 
B-2 shows the ADDS Regent Model 200 configuration. 


Table B-2 ADDS Regent Model 200 Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

CD 

OA 

Line Feed 

CH 

01 

SOH 

CL 

15 

NAKorBS 

CR 

06 

ACK 

CU 

1A 

SUB 

MD 

OA 

Line Feed 

MH 

1B59 20 20 


ML 

15 

NAK or BS 

MR 

06 

ACK 

MU 

1A 

SUB 

AC 

IB 59 

ESC Y 

EK 

not available 


ER 

1B6B 

ESCK 

ES 

OC 

FF 

XA 

14 

DC4 

AO 

20 

SP 

AX 

F 


XF 

IB 45 

ESCE 

XZ 

1B6C 

ESC! 

AB 

5C 


AV 


24 


Command File; ADDS.CRT 


AFCD=0A 

AFCU=1A 

AFML=15 

AFMH=1B59 20 20 

AV=24 

AFER=lb6b 

AX=F 

AB=5C 


AFCL=15 

AFCH=01 

AFMR=06 

AFEK= 

AFXA=14 

AFAC=1B59 

AFXF=1B45 


NOTE 


AFCR=06 

AFMD=0A 

AFMU=1A 

AFER=1B6B 

AFES=0C 

AO =20 

AFXZ=1B6C 


You must enter DEL CHAR instead of CNTL-F for the delete 
character. You must enter DEL LINE instead of CNTL-Z for 
delete line. You must enter CNTL-T instead of CNTL-A for 
delete right. You must enter the backslash (\) instead of 
ESCAPE. 
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ADDS Viewpoint 3A Plus 


This terminal has a 24-line CRT display with 80 characters per line. Table B-3 
shows the ADDS Viewpoint 3A Plus configuration. 


Table B-3 ADDS Viewpoint 3 A Plus Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

CD 

OA 

Line Feed 

CL 

08 

BS 

CR 

OC 

FF 

CU 

OB 

VT 

CH 

1E 

RS 

MD 

OA 

Line Feed 

ML 

08 

BS 

MR 

OC 

FF 

MU 

OB 

VT 

MH 

1E 

RS 

EK 

not available 


ER 

1B59 

ESCY 

EL 

1B 54 

ESC 

ES 

1B2A 

ESC 

AC 

1B3D 

ESC = 

AO 

20 

SP 

AX 


F 

AV 


24 


Command File: ADDS. CRT 


AFCD=0A 

AFCU=0B 

AFML=08 

AFMH=1E 

AFEL=1B54 

AO = 20 


AFCL=08 
AFCH = 1E 
AFMR=0C 
AFEK= 
AFES=1B2A 
AX = F 


AFCR=0C 

AFMD=0A 

AFMU=0B 

AFER=1B59 

AFAC=1B3D 

AV=24 
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Beehive Mini-Bee 

You can format the Beehive Mini-Bee terminal to display either 12 or 25 lines of 
80 characters per line. Only the 25-character format is usable with PSCOPE. Each 
character is generated in a 5 by 7 dot matrix. The maximum transmission rate for 
this terminal is 9600 baud. Note that you must change the ESCAPE character so 
that the default ESCAPE code can be used; choosing the fK is a personal 
preference. Table B-4 shows the Beehive Mini-Bee configuration. 


Table B-4 Beehive Mini-Bee Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

CD 

1B42 

ESCB 

CH 

1B48 

ESCH 

CL 

1B44 

ESCD 

CR 

1B43 

ESCC 

CU 

1B 41 

ESC A 

MD 

IB 42 

ESCB 

MH 

IB 48 

ESCH 

ML 

IB 44 

ESCD 

MR 

IB 43 

ESCC 

MU 

1B41 

ESC A 

EL 

1B4B 

ESCK 

ER 

1B4A 

ESC J 

B 

OB 

IK 

AV 


24 


Command File: MICROB.CRT 


AFCU=1B41 
AFCL=1B44 
AFMD = 1B42 
AFMH=1B48 
AB=0B 


AFCD = 1B42 
AFCH=1B48 
AFMR=1B43 
AFEL=1B4B 
AV=24 

NOTE 


AFCR=1B43 

AFMU=1B41 

AFML=1B44 

AFER=1B4A 


You must enter CNTL-K instead of ESCAPE. 
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DEC VT52 

The DEC VT52 displays 24 lines of 80 characters per line. The characters are 
generated in a 7 by 9 dot matrix. The maximum transmission rate is 19.2K baud. 
Note that you must change the ESCAPE character so that the default ESCAPE 
code can be used; choosing CNTL-K (| K) is a personal preference. The DEC 
VT52 does not have a HOME key. Choosing CNTL-0 (| 0) for the HOME func- 
tion is a personal preference. Table B-5 shows the DEC VT52 configuration. 


Table B-5 DEC VT52 Configuration 


Function 

Code 

Hexadecimal 

Value 

Graphic or 
ASCII Name 

CD 

1B42 

ESCB 

CH 

OF 

10 

CL 

1B44 

ESCD 

CR 

1B43 

ESCC 

CU 

1B41 

ESC A 

MD 

1B42 

ESCB 

MH 

1B48 

ESCH 

ML 

1B44 

ESCD 

MR 

1B43 

ESCC 

MU 

1B41 

ESC A 

AC 

1B53 

V/ 

c:ox-» 1 

W 

F 


AO 

20 

SP 

AX 

F 


EL 

1B4B 

ESCK 

ER 

1B4A 

ESC J 

ES 

not available 


EK 

not available 


AV 


24 

B 

OB 

IK 


Command File: VT52.CRT 


AFCU = 1B41 
AFCL=1B44 
AFMD = 1B42 
AFMH=iB48 
AFEL = 1B4B 
AV=24 
AX = F 


AFCD = 1B42 
AFCH=0F 
AFMR = 1B43 
AFES = 
AFEK= 

AFAC = 1B59 
AW=F 


AFCR=1B43 
AFMU = 1B41 
AFML=1B44 
AFER=1B4A 
AB=0B 
AO = 20 


NOTE 


You must enter CNTL-K instead of ESCAPE. You must enter 
CNTL-0 instead of HOME. 
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DEC VT100 

You can format the DEC VTIOO terminal with 14 lines of 132 characters per line 
or 24 lines of 80 characters per line. Only the 24-line format is compatible with 
PSCOPE. The characters are generated in a 7 by 9 dot matrix. The maximum trans- 
mission rate is 19. 2K baud. You can choose between the DEC VT52 compatible 
and the ANSI standard (X3.41-1974, X3.64-1977) compatible terminal escape se- 
quences for cursor control and screen erase functions. The ANSI codes are given 
in the following table. See the DEC VT52 description for the VT52 codes. Note 
that you must change the ESCAPE character so that the default ESCAPE code can 
be used; choosing CNTL-K (| K) is a personal preference. The DEC VTIOO termi- 
nal does not have a HOME key. Choosing CNTL-0 (f 0) for the HOME function 
is a personal preference. Table B-6 shows the DEC VTIOO configuration. 


Table B-6 DEC VTIOO Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

CD 

1B42 

ESCB 

CH 

OF 

to 

CL 

IB 44 

ESCD 

CR 

1B43 

ESCC 

CU 

1B41 

ESC A 

MD 

1 B 5B 42 

ESC [B 

MH 

1 B 5B 48 

ESC [H 

ML 

1 B 5B 44 

ESCID 

MR 

1 B 5B 43 

ESCIC 

MU 

1B5B41 

ESC [A 

EK 

1 B 5B 30 4B 

ESC [ 0 K 

ER 

1 B 5B 30 4A 

, ESC [ 0 J 

ES 

not available 


EL 

1 B 5B 4B 


W 

F 


AV 


24 

B 

OB 

|K 


Command File: VTIOO.CRT 


AFCU=1B41 
AFCL = 1B44 
AFMD = 1B5B 42 
AFMH=1B5B48 
AFEK=1B5B30 4B 
AV=24 


AFCD = 1B42 
AFCH=0F 
AFMR=1B5B43 
affs= 

AFEL=1B5B4B 

AW=F 


AFCR=1B43 
AFMU = 1B5B41 
AFML=1B5B44 
AFER=1B5B30 4A 
AB=0B 


NOTE 


You must enter CNTL-K instead of ESCAPE. You must enter 
CNTL-0 instead of HOME. 
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Hazeltine 1 420 

This terminal displays 24 lines, with 80 characters per line. The maximum trans- 
mission rate is 9600 baud. You may choose between the tilde key or the ESC char- 
acter as the control sequence lead-in. To use the ESC character as the lead-in, sub- 
stitute escape (IB) for the tilde (7E) in the command file, and add the function 
code AB=7E. When using the escape lead-in, the tilde must be typed instead of 
escape. Table B-7 shows the Hazeltine 1420 configuration. 


Table B-7 Hazeltine 1420 Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

CD 

OB 

VT 

CH 

12 

DC2 

CL 

08 

BS 

CR 

10 

DLE 

CU 

OC 

FF 

MD 

7E OB 

~ VT 

MH 

7E 12 

~ DC2 

ML 

08 

BS 

MR 

10 

DLE 

MU 

7E OC 

~ FF 

MB 

OD 

CR 

ES 

not available 


ER 

7E 18 

- CAN 

EK 

not available 


EL 

7EOF 

~ SI 

AC 

7E 11 

~ DC1 

IL 

7E 1A 

~ SUB 

DL 

7E 13 

~ DC3 

AV 


24 

IG 

7E 

~ 


Command File: 1420T.MAC 


AV=24 
AFCD = 0B 
AFCH = 12 
AFMR=10 
AFMB=0D 
AhJfcK = 

AFIL = 7E1A 


AFIG = 7E 
AFCR=10 
AFMU = 7E0C 
AFML=8 
AFES = 

AFEL = 7E OF 
AFDL=7E13 


AFCU=0C 
AFCL=8 
AFMD = 7E OB 
AFMH=7E12 
AFER = 7E18 
AFAC=7E 11 
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Hazeltine1510 

The Hazeltine 1510 terminal displays 24 lines of 80 characters per line. The charac- 
ters are generated in a 7 by 10 dot matrix. The maximum transmission rate is 
19.2K baud. You can choose between the ESC or the tilde character ( ~ ) as the 
control sequence lead-in. However, if you use ESC, you must change the BREAK 
character, so the tilde is easier to use. Table B-8 shows the Hazeltine 1510 configu- 
ration with the tilde lead-in and Table B-9 shows the Hazeltine 1510 configuration 
with the ESC lead-in. 


Table B-8 Hazeltine 1510 Configuration (Tiide Lead-in) 


Function 

Code 

Hexadecimal 

Value 

( ~ lead-in ) 

Graphic or 
ASCII Name 

CD 

OB 

~ VT 

CH 

12 

~ DC2 

CL 

08 

~ BS 

CR 

10 

~ DLE 

CU 

OC 

FF 

MD 

7E OB 

- VT 

MH 

7E 12 

- DC2 

ML 

08 

- BS 

MR 

10 

- DLE 

MU 

7E OC 

- FF 

MB 

OD 


AC 

7E 11 

- DC1 

EK 

not available 


ER 

7E 18 

- CAN 

ES 

not available 


EL 

7E OF 

— 

XP 

OF 

SI 

IL 

7E 1A 

- SUB 

DL 

7E 13 

- DC3 

AV 


24 


Command File; 1510T.CRT 


AV=24 

AFCD=0B 

AFCH=12 

AFMR=10 

AFMB=0D 

AFEK= 

AF1L=7E1A 


AF1G=7E 
AFCR=10 
AFMU=7E OC 
AFML=8 
AFES = 
AFEL=7E OF 
AFDL=7E13 


AFCU=0C 

AFCL=8 

AFMD = 7E0B 

AFMH=7E12 

AFER=7E18 

AFAC=7E11 
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Table B-9 Hazeltine 1510 Configuration (ESC Lead-in) 


Function 

Code 

Hexadecimal 

Value 

(ESC lead-in) 

Graphic or 
ASCII Name 

CD 

OB 

ESC VT 

CH 

12 

ESCDC2 

CL 

08 

ESC BS 

CR 

10 

ESCDLE 

CU 

OC 

ESC FF 

MD 

IB OB 

ESC VT 

MH 

IB 12 

ESC DC2 

ML 

08 

ESCBS 

MR 

10 

ESC DLE 

MU 

1B0C 

ESC FF 

MB 

OD 


EK 

not available 


ER 

IB 18 

ESC CAN 

ES 

not available 


EL 

IB OF 


IL 

IB 1A 

ESC SUB 

DL 

IB 13 

ESC DC3 

XP 

OF 

SI 

AC 

IB 11 

ESC DC1 

AV 


24 

B 

7E 



Command File: 1510E.CRT 


AV=24 
AFCU= OC 
AFCL=8 
AFMD = 1B0B 
AFMH = 1B12 
AFER=1B18 
AFAC=1B11 


AB=7E 
AFCD= OB 
AFCH= 12 
AFMR=10 
AFMB=0D 
AFEK= 
AFIL = 1B1A 


AFIG = 1B 

AFCR=10 

AFMU=1B0C 

AFML=8 

AFES = 

AFEL=1B0F 

AFDL=1B13 
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Intel Series- 1 HE 

The Intel Series-IIIE terminal displays 24 lines of 80 characters per line. The maxi- 
mum transmission rate is 19. 2K baud. Table B-10 shows the Intel Series-IIIE 
configuration. 


Table B-10 Intel Series-IIIE Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

ER 

1B53 

ESCS 

AC 

IB 59 

ESCY 

IL 

IB 57 60 3F 

ESC W '? 

DL 

1 B 57 3F 60 

ESC W ?' 

EL 

1B52 

ESCR 

AX 


F 

AO 

20 

SP 


Command File; 511I0C.MAC 

AX=F AO=20 AFER=1B53 

AFAC= IB 59 AFIL= IB 57 60 3F AFDL= IB 57 3F 60 

AFEL=1B52 

NOTE 

A Series-IIIE with 511 IOC firmware must use this macro to take 
advantage of the enhanced functionality. 
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Lear Siegler ADM-3A 


The Lear Siegler ADM-3 A terminal displays 24 lines of 80 characters per line. The 
characters are generated in 5 by 7 dot matrix. The maximum transmission rate is 
1 9.2K baud. Table B-1 1 shows the Lear Siegler ADM-3 A configuration. 


Table B-11 Lear Siegler ADM-3 A Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

CD 

OA 

LF 

CH 

1E 

RS 

CL 

08 

BS 

CR 

OC 

FF 

CU 

OB 

VT 

MD 

OA 

LF 

MH 

IE 

RS 

ML 

08 

BS 

MR 

OC 

FF 

MU 

OB 

VT 

EK 

not available 


ER 

not available 


ES 

1A 

SUB 

AX 

F 


AO 

20 

SP 

AC 

1B3D 

ESC = 

AV 


24 


Command File: LEAR.CRT 


AFCU = 0B 
AFCL = 08 
AFMD=0A 
AFMH=1E 
AFER = 
AX=F 


AFCD=0A 

AFCH=1E 

AFMR=0C 

AV=24 

AFEK= 

AO =20 


AFCR=0C 
AFMU=0B 
AFML = 08 
AFES=1A 
AFAC = 1B3D 
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Televideo 91 0 Plus 

The Televideo 910 Plus displays 24 lines of 80 characters per line. The maximum 
transmission rate is 19.2K baud. Table B-12 shows the Televideo 910 Plus 
configuration. 


Table B-12 Televideo 910 Plus Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

CD 

16 

SYN 

CH 

IE 

RS 

CL 

08 

BS 

CR 

OC 

FF 

CU 

OB 

VT 

MD 

16 

SYN 

MH 

IE 

RS 

ML 

08 

BS 

MR 

OC 

FF 

MU 

OB 

VT 

ES 

1B2B 

ESC 4- 

ER 

IB 59 

ESC Y 

EK 

not available 


EL 

IB 54 

ESCT 

AC 

IB 3D 

ESC - 

AX 


F 

AO 

20 

SF 

IL 

1B45 

ESCE 

DL 

IB 52 

ESCR 

AV 


24 


Command File: TV910P.MAC 


AFCU=0B 

AFCL=08 

AFMD = 16 

AFMH=1E 

AFER=1B59 

AFAC=1B3D 

AF1L=1B45 


AFCD = 16 

AFCH=1E 

AFMR=0C 

AV=24 

AFEK= 

AX=F 

AFDL=1B52 


AFCR=0C 

AFMU=0B 

AFML=08 

AFES=1B2B 

AFEL=1B54 

AO =20 
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Televideo 925 and 950 

The Televideo 925 and 950 displays 24 lines of 80 characters per line. The maxi- 
mum transmission rate is 19. 2K baud. Table B-13 shows the Televideo 925 and 
950 configuration. 


Table B-13 Televideo 925 and 950 Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

XA 

01 

NUL 

XF 

06 

ACK 

XU 

15 

NAK 

XX 

18 

CAN 

XZ 

1A 

SUB 

CD 

16 

SYN 

CH 

IE 

RS 

CL 

08 

BS 

CR 

OC 

FF 

CU 

OB 

VT 

MB 

OD 

CR 

MD 

16 

SYN 

MH 

IE 

RS 

ML 

08 

BS 

MR 

OC 

FF 

MU 

OB 

VT 

ES 

1B2B 

ESC + 

ER 

1B59 

ESCY 

EK 

not available 


DL 

IB 52 

ESCR 

EL 

IB 54 

ESCT 

IL 

IB 45 

ESCE 

AC 

IB 3D 

ESC = 

AO 

20 

SP 

AX 


F 

AV 


24 

AB 

IB 

ESC 

AR 

7F 

DEL 

BK 

20 

SP 


Command File: TV925.MAC 


AV=24 

AFBK=20 

AFXU=15 

AFCD = 16 

AFCR=0C 

AFMD = 16 

AFMR=0C 

AFER=1B59 

AFEL=1B54 

AO = 20 


AB=1B 

AFXA=1 

AFXX=18 

AFCH=1E 

AFCU=0B 

AFMH=1E 

AFMU = 0B 

AFEK = 

AFIL = 1B45 

AX=F 


AR = 7F 

AFXF=6 

AFXZ=1A 

AFCL=08 

AFMB=0D 

AFML=08 

AFES = 1B2B 

AFDL = 1B52 

AFAC=1B3D 
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Zentec 

The Zentec displays 24 lines of 80 characters per line. The maximum transmission 
rate is 19.2K baud. To rub out a character on this terminal you must use the delete 
key, SHIFT plus ESC. Table B-14 shows the Zentec configuration. 


Table B-14 Zentec Configuration 


Function 

Hexadecimal 

Graphic or 

Code 

Value 

ASCII Name 

XA 

1 

SOH 

XF 

6 

ACK 

XU 

15 

NAK 

XX 

18 

CAN 

XZ 

1A 

SUB 

CD 

OA 

LF 

CH 

IE 

RS 

CL 

08 

BS 

CR 

OC 

FF 

CU 

OB 

VT 

MB 

OD 

CR 

MD 

OA 

LF 

MH 

IE 

RS 

ML 

08 

BS 

MR 

OC 

FF 

MU 

OB 

VT 

ES 

1B2B 

ESC + 

ER 

IB 59 

ESC Y 

EK 

not available 


DL 

IB 52 

ESCR 

EL 

IB 54 

ESCT 

IL 

IB 45 

ESCE 

AC 

IB 3D 

ESC = 

AO 

20 

SP 

AX 


F 

BE 

20 

SP 

AV 


24 

AB 

IB 

ESC 

AR 

7F 

DEL 


Command File: ZENTEC.MAC 


AV=24 

AFXA=1 

AFXX = 18 

AFCH=1E 

AFCU=0B 

AFMH=1E 

AFMU=0B 

AFEK= 

AFIL=1B45 

AX=F 


AB=1B 

AFXF=6 

AFXZ=1A 

AFCL=08 

AFMB=0D 

AFML=08 

AFES = 1B2B 

AFDL=1B52 

AFAC=1B3D 

AFBK=20 


AR=7F 
AFXU=15 
AFCD = 0A 
AFCR=0C 
AFMD = 0A 
AFMR=0C 
AFER=1B59 
AFEL = 1B54 
AO =20 
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APPENDIX C 
ADDITIONAL INFORMATION FOR 

SERIES III USERS 


This appendix contains specific information on the Intellec Series III development 
system. It covers the following subjects: 

• Series III program development process (and related manuals) . 

• Hardware and software required. 

• User programs supported. 

• System resources used by the debugger. 

• System-specific examples of debugger invocation line, sign-on message, and 
commands. 


Operation of the Series III 

The following manuals describe the general operation of the Series III: 

• Intellec® Series III Microcomputer Development System Product Overview, 
order number 121575 

• Intellec® Series III Microcomputer Development System Console Operating 
Tytctrit/*HnytQ rwAe^T mimKpkr 191 

• Intellec® Series III Microcomputer Development System Programmer 's Reference 
Manual, order number 121618 


Program Development Process 

Figure 1-1 shows how the debugger fits into your program development process. 
Figure C-1 shows the same process. The following manuals will provide informa- 
tion on the different stages of your program development. 

• ISIS-II CREDIT™ CRT-Based Text Editor User’s Guide, 
order number 9800902 

• AEDIT TEXT EDITOR User’s Guide, order number 121756 

• Pascal-86 User’s Guide, order number 121539 

• PL/M-86 User’s Guide for 8086-Based Development System, 
order number 121636 

• FORTRAN-86 User’s Guide, order number 121570 

• iAPX 86, 88 Family Utilities User ’s Guide, order number 121616 




Additional Information for Series III Users 


PSCOPE-86 User’s Guide 
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Figure C-1 Series III Program Development Process 


Hardware and Software Required 

You need the following hardware and software to run the debugger: 

• Intellec Series III development system (run release 2.0 or later) . 

• ISIS operating system (release 4. 1 or later) . 

• At least one single- or double-density flexible disk drive, a hard disk unit 
plus a single- or double-density flexible drive, or a remote disk on an NDS I 
orNDS II. 

• Pascal compiler (release 2.0 or later), PL/M-86 compiler (release 2.0 or 
later) , or FORTRAN-86 compiler (release 2.0 or later) . 

• 8086-based utilities. 

• PSCOPE high-level program debugger. 
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Additional Information for Series III Users 


User Programs Supported 

The amount of memory available to your program (the program under debug) 
depends upon the amount of memory in your system. You can expand the Series 
III up to one megabyte of memory addressable by the 8086. PSCOPE requires ap- 
proximately 11 OK bytes. You must add more memory to accommodate additional 
workspace and your program. 

Your program must be a load-time locatable (LTL) or a position independent code 
(PIC) object module produced by LINK86 with the BIND control. You must pro- 
duce the object modules used as input to LINK86 with either a Pascal-86 compiler 
(release 2.0 or later), a PL/M-86 compiler (release 2.0 or later), or a 
FORTRAN-86 compiler (release 2.0 or later) with the DEBUG control. Because 
the reliability of some debug functions can be affected by cross-statement compiler 
optimizations, you must use OPTIMIZE (0) . 


System Resources Used 

The debugger requires certain system resources, such as memory space and open 
files, that can affect your program. 


Memory 

The debugger occupies 11 OK bytes of memory, including space for symbol and 
line number information. 

To reduce memory usage, the debugger provides for virtual storage of compiler- 
generated debug information. Symbol table information (from the compiler) is 
sent out to disk if necessary. Your program must reside in memory, however. 


File Requirements 

Under the Series III operating system, up to six open files are available for an 
application, plus terminal input. (Terminal output does not count as an open file.) 
Terminal input does not count against the total of six open files allowed because 
the operating system shares terminal input between PSCOPE and your program. 

Of those six files, PSCOPE may require one or more files from each of the follow- 
ing groups: 

• Console input 

• Virtual symbol table 

• LOAD, HELP, PUT, INCLUDE, CRT, MACRO, PSCOPE overlay 

• List 

The number of open files increases if you have nested open files, such as a PUT 
command inside of an INCLUDE file. 
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Other Resources Required 

The debugger requires the following additional host system resources: 

• The software interrupt 3 (the one-byte, debugger-oriented INT instruction) 

• The trap flag (used for single-stepping) 

• The CNTL-C trap (system call DQ$TRAP$CC) 

Your program should not use these host system resources. 

In addition, PSCOPE uses interrupts 0, 4, 5, 16, 17, and 20 through 31 for error 
handling and floating point operations. However, your program can use these 
interrupts, since PSCOPE maintains separate copies of these interrupt vectors for 
itself and your program. 


Invocation Line 

To invoke the debugger in the 8086 execution environment of the Series III, pre- 
face the invocation line with the RUN command. The ISIS-II operating system 
prompt is a hyphen (-) . 

The general format of the invocation is: 

-RUN [:Fn:] PSCOPE [controls] 

or 

>[:Fn:] PSCOPE [controls] 

Where: 

:Fn: is the disk in drive n. The n can be 0 through 9. 

controls is any number of invocation controls from the list specified in 
Chapter 3. 

PSCOPE signs on with the following message: 

SERIES-lli PSCOPE-86, Vx.y 

Example 

The following example shows the beginning of a PSCOPE debugging session: 

-RUN PSCOPE MACRO(:F1 :PROCS.MAC) 

SERIES-III PSCOPE-86, Vx.y 

*LOAD:F1:DC.86 

«GO 
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APPENDIX D 
ADDITIONAL INFORMATION FOR 

SERIES IV USERS 


T his appendix contains specific inf ormation on the Intellec Series IV development 
system. It covers the following subjects: 

• Series IV program development process (and related manuals) . 

• Hardware and software required. 

• User programs supported. 

• System resources used by the debugger. 

• System-specific examples of the debugger invocation line, sign-on message, 
and commands. 


Operation of the Series IV 

The following manuals describe the general operation of the Series IV: 

• Intellec® Series IV Microcomputer Development System Overview^ 
order number 121752 

• Intellect Series IV Operating and Programming Guide^ order number 121753 

• Intellec® Series IV ISIS-IV User's Guide, order number 121880 


Program Deveiopment Process 

Figure 1-1 shows how the debugger fits into your program development process. 
Figure D-1 shows the same process. The following manuals provide information 
that will aid in your program development. 

• ISIS-IV CREDIT^^ CRT-Based Text Editor User’s Guide, 
order number 9800902 

• AEDIT TEXT EDITOR User’s Guide, order number 121756 

• Pascal 86 User’s Guide, order number 121539 

• PL/M-86 User’s Guide for 8086-Based Development System, 
order number 121636 

• FORTRAN-86 User’s Guide, order number 121570 

• lAPX 86,88 Family Utilities User’s Guide, order number 121616 





Additional Information for Series IV Users 


PSCOPE-86 User’s Guide 


Hardware and Software Required 

You need the foiiowing hardware and software to run the debugger: 

• Intellec Series IV development system. 

• iNDX operating system. 

• At least one single- or double-density flexible disk drive, a hard disk unit 
plus a single- or double-density 5 1/4 inch floppy, or a remote disk on an 
NDSIorNDSII. 

• Pascal compiler (release 2.0 or later), PL/M-86 compiler (release 2.0 or 
later) , or FORTRAN-86 compiler (release 2.0 or later) . 

• 8086-based utilities. 

• PSCOPE high-level program debugger. 
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Figure D-1 Series IV Program Development Process 


D-2 








PSCOPE-86 User’s Guide 


Additional Information for Series IV Users 


User Programs Supported 

The amount of memory available to your program (the program under debug) 
depends upon the amount of memory in your system. You can expand the Series 
IV up to one megabyte of memory addressable by the 8086. PSCOPE requires ap- 
proximately 11 OK bytes. You must add more memory to accommodate additional 
workspace and the user program. 

Your program must be a load-time beatable (LTL) or a position independent code 
(PIC) object module produced by LINK86 with the BIND control. You must pro- 
duce the object modules used as input to LINK 8 6 with either a Pascal- 8 6 compiler 
(release 2.0 or later), a PL/M-86 compiler (release 2.0 or later), or a 
FORTRAN-86 compiler (release 2.0 or later) with the DEBUG control. Because 
the reliability of some debug functions can be affected by cross-statement compiler 
optimizations, you must use OPTIMIZE (0) . 


System Resources Used 

The debugger requires certain system resources, such as memory space and open 
files, that can affect your program. 


Memory 

The debugger occupies 11 OK bytes of memory, including space for symbol and 
line number information. 

To reduce memory usage, the debugger provides for virtual storage of compiler- 
generated debug information. Symbol table information (from the compiler) will 
be sent out to disk if necessary. Your program must reside in memory, however. 


File Requirements 

Under the Series IV operating system, up to six open files are available for an 
application, plus terminal input. (Terminal output does not count as an open file.) 
Terminal input does not count against the total of six open files allowed because 
the operating system shares terminal input between PSCOPE and your program. 

Of those six files, PSCOPE may require one or more files from each of the follow- 
ing groups: 

• Terminal input 

• Virtual symbol table 

• LOAD, HELP, PUT, INCLUDE, CRT, MACRO, or PSCOPE overlay 

• List 

The number of open files increases if you have nested open files, such as a PUT 
command inside of an INCLUDE file. 
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other Resources Required 

The debugger requires the following additional host system resources: 

• The software interrupt 3 (the one-byte, debugger-oriented INT instruction) . 

• The trap flag and interrupt 1 (used for single-stepping) . 

• The CNTL-C trap (system call DQ$TRAP$CC) . 

Your program or any background program should not use these host system 
resources. 

In addition, PSCOPE uses interrupts 0, 4, 5, 16, 17, and 20 through 31 for error 
handling and floating point operations. Your program can use these interrupts, 
since PSCOPE maintains separate copies of these interrupt vectors for itself and 
your program. However, a background program must not use any of these 
interrupts. 


Invocation Line 

The general format of the invocation is as follows: 

/W/ PSCOPE [controls] 
or 

PSCOPE [controls] 

Where: 

controls is any number of invocation controls from the list specified in 
Chapters. 

PSCOPE signs on with the following message: 

SERIES-IV PSCOPE-86, Vx.y 

Example 

The following example shows the beginning of a PSCOPE debugging session: 

-PSCOPE MACRO(PROCS.MAC) 

SERIES-IV PSCOPE-86, Vx.y 

«LOAD DC.86 
«GO 
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APPENDIX E 
SAMPLE PROGRAM LISTING 


This appendix contains the sample program DC referred to throughout this 
manual. 


SERIES-in P»SCil-86, V2.0 


Source File; ;F7:DC7,PAS 
Object File; :F7;DC7.0BJ 
Controls Specified: XREF, DEBUG. 

STMT LINE NESTING SOURCE TEXT; ;F7;DC7.PAS 

1100 (e This program implements an interactive Desk Calculator, It 

accepts lines of text as input. Each line should contain one 
expression. Each line is parsed^ evaluated, and the result 
is printed. The expressions are allouied to contain embedded 
assignment statements to single-letter variables. An error 
will abort the evaluation of the current expression. *) 

program dc (input, output): 

2 10 0 0 label 1000, 9999; 

3 12 0 0 const max_l ine_length = 40; 

4 14 0 0 type error_class = ( i llegal_token , 1 ine_too_long , end_of_iine, 

missing_r_paren, error_in_expression , error_in_factor , 

error_in_statement , error_in_term) ; 

5 18 0 0 token^class = (add_op, mul_op, assign, l^paren, 

r_paren, variable, int_const, line_end); 


6 21 0 0 

6 22 0 1 

7 23 0 1 

8 24 0 1 

9 25 0 1 

10 26 0 1 

11 27 0 1 

12 28 0 1 

13 29 0 1 

14 30 0 1 

15 31 0 1 


token = record 

case class : token_class of 

add_op : (add_op_ualue ; char); 

rool^op ; (mul_op_ualue ; char); 

assign : O; 

l_paren : O; 

r_paren : ( ) ; 

variable : ( variable_value : char); 
int_const ; ( int_const_ualue : integer); 
line^end : (); 

end (♦ record * ) ; 


16 33 0 0 text_buffer * record 

16 34 0 1 status : (empty, full); 

17 35 0 1 length : 0 .. max_l ine.length; 

18 36 0 1 index : 0 .. max_l ine_length ; 

19 37 0 I last_index ; 0 .. max_line_length; 

20 38 0 1 str ” : packed array C 1 . .max_l ine_length3 of char 

end <* record «); 


21 41 0 0 var t ; token; 

22 42 0 0 c ; char; 

23 43 0 0 buffer : text_buffer; 


24 45 0 0 


var iable.table : array! ’a’ . . ’z’ 3 of integer; 


25 47 0 0 

26 49 1 0 

26 50 1 1 

27 51 1 1 


(» *) 

procedure error(e : error_class ) ; (e print error & restart *) 
begin 

write (' (buffer. last_index+3) , DC Errors M; 
case e of 
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SERIES-III Pascal-86, V2.0 
ERROR 


ST.1T 

LINE 

NESTING 

SOURCE TEXT: :F7:DC7.PAS 



28 

52 

1 

2 

i 1 legal^token 

: write 

[’Illegal token’); 

29 

53 

1 

2 

1 ine^too^long 

: write 

[’Input line too long’); 

30 

54 

1 

2 

end^of _1 ine 

: write 

[ ’End of line’ ) ; 

31 

55 

1 

2 

missing_r_paren 

: write 

[’Missing right paren’); 

32 

56 

1 

2 

error_in_f actor 

: write 

[’Illegal factor’); 

33 

57 

1 

2 

error_in_term 

: write 

[’Error detected in term’); 

34 

53 

1 

2 

error_in_expression 

: write 

[’Error detected in expression 

35 

59 

1 

2 

error_in_statement 

: write 

[’Illegal statement’); 

36 

60 

1 

2 

end (« case e); 



38 

61 

1 

1 

wr i teln; 



39 

62 

1 

1 

goto 9999; 



40 

63 

1 

1 

end i* error ♦); 




41 65 0 0 

42 67 1 0 

42 68 1 1 

43 69 1 1 

44 70 1 1 

45 71 1 1 

45 72 1 2 

46 73 1 2 

48 74 1 2 

49 75 1 2 

50 76 1 3 

51 77 1 3 

52 79 1 2 

54 80 1 2 

55 81 1 2 

57 82 1 1 

58 83 1 1 

59 84 1 1 

60 85 1 1 

61 87 0 0 


62 90 1 0 

63 91 2 0 

63 92 2 1 


function upper _case < c : char): boolean; (* true if c is upper case 
begin 

upper_case := ('A* <= c) and (c <= 'ZM 
end ; 

function 1 ower_case < c : char): boolean; (# true if c is lower case *) 
begin 

lower_casB ;= (’a* <= c) and (c <= ^zM 
end ; 

68. 105 1 0 (# *) 

procedure get_char; (* set c to next char in line ♦> 


64 95 1 0 

65 96 2 0 

65 97 2 1 


66 100 1 0 
67 101 2 0 

67 102 2 1 


{* #) 

procedure get^line; {» input line 8: set c to 1st char of line 
begin i* get_Tine *) 
buf f er . 1 ength := 0; 

buf fer . status := empty; 
buf f er . 1 ast^index := 1; 
repeat 
write(' 

while eof do reset! input) ; 
while not eoln do 

if buf fer . length < max_l i^ne_length then begin 
buf fer . length := buf fer . 1 ength + 1; 
readibuffer.strCbuffer. length]) 
end 

else error ( 1 ine_too_long ) ; 
readln ; 

until buf fer . length > 0; 


buf fer . status := full; 
buffer. index := 1; 

c := buffer.strCbuffer. index]; 

end (.* get_l ine ♦) ; 

i* - - *) 


procedure get_token; (* scan line & set t to its value #) 

function digit(c: char): boolean; (♦ true if c is a digit *) 
begin 

digit := (’O' <= c) and (c <= ^9M 
end ' 
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Sample Program Listing 


SERIES-III Pasc4l-86, V2.0 
GET_CHAR 


STMT 

LINE 

NESTING 

SOURCE TEXT; ;F7:DC7.PAS 


69 

107 

2 

0 

begin (* get char ♦) 


69 

108 

2 

1 

if buf fer . status = empty then get line 


70 

109 

2 

1 

else begin 


71 

no 

2 

2 

if buffer, index < buf f er . length then begin 


72 

111 

2 

3 

buffer. index ;= buffer. index + 1; 


73 

112 

2 

3 

c := buffer. strCbuffer. index] ; 


74 

113 

2 

3 

end 


75 

114 

2 

2 

else begin 


76 

115 

2 

3 

c := cr; 


77 

116 

2 

3 

buf f er . status := empty 
end 


73 

118 

2 

2 

end 


79 

119 

2 

1 

end {* get_char 


80 

121 

1 

0 

(* *) 

begin (# get_token; scan line & set t to its ualue #) 


80 

124 

1 

1 

while c = ' ' do get_char; {* skip leading spaces 

*) 

82 

125 

1 

1 

buf f er . last^index ;= buf fer . index j (» for error reporting 

♦ ) 

83 

127 

1 

1 

if lower case(c) then begin (* lower case variable 

#) 

84 

128 

1 

2 

t. class ;= variable; 


85 

129 

1 

2 

t. variable value := c; 


86 

130 

1 

2 

get char; 


87 

131 

1 

2 

end 


88 

133 

1 

1 

else if upper case(c) then begin (* upper case variable 

♦ ) 

90 

134 

1 

2 

t. class variable; 


91 

135 

1 

2 

t . variable_value ;= chr(ord(c) + (ord(^aM - ord(^AM)) 


92 

136 

1 

2 

get_char ; 


93 

137 

1 

2 

end 


94 

139 

1 

1 

else if digit(c) then begin (* integer constant *) 


96 

140 

1 

2 

t. class ;= int_const; 


97 

141 

1 

2 

t . int_const_value ;= 0; 


98 

142 

1 

2 

while digitTc) do begin 


99 

143 

1 

3 

t.int const value ;= 10*t.int const value + ord(c) - ord 

100 

144 

1 

3 

get char; 


101 

145 

1 

3 

end ; 


103 

146 

1 

2 

end 


104 

148 

1 

1 

else if c = cr then begin end of line #) 


106 

149 

1 

2 

t. class := line end; 


107 

150 

1 

2 

c := If; 


108 

151 

1 

2 

end 


109 

153 

1 

1 

else begin (♦ symbol; +-#/;= i 

) 

110 

154 

1 

2 

case c of 


111 

155 

1 

3 

: begin t. class add op; t.add op value 

c; 

115 

156 

1 

3 

W* : begin t. class := mul op; t.mul op ualue ; = 

c; 

119 

157 

1 

3 

: begin 


119 

158 

1 

4 

get char; 


120 

159 

1 

4 

if c = *=' then t. class := assign 


121 

160 

1 

4 

else error ( i 1 legal token); 


123 

161 

1 

4 

end ; 
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SERIES-III Pascal-86, V2.0 
GET_TOKEN 


STHT 

LINE 

NESTING 

SOURCE TEXT: :F7;DC7.PAS 

125 

162 

1 

3 

: t. class := 1 paren; 

126 

163 

1 

3 

* )* ; t .class := r paren; 

127 

164 

1 

3 

: goto 1000; 

128 

165 

1 

3 

otherwise error ( i 1 legal token); 

130 

166 

1 

3 

end (♦ case *) ; 

132 

167 

1 

2 

get char; 

133 

168 

1 

2 

end (* begin ♦) ; 

135 

170 

1 

1 

end (♦ get^token *); 

136 

172 

0 

0 

{ ♦ * ) 

procedure factor(var factor ualue : integer); 

137 

174 

1 

0 

(* parse: <uariable> <expression>3 \ ''<"<expres5ion>")" 1 <number> #) 





uar expression_ualue : integer; 

138 

176 

1 

0 

variable index ; char; 

139 

177 

1 

0 

begin (* factor ♦) 

139 

178 

1 

1 

case t. class of 

140 

179 

1 

2 

variable : begin 

140 

180 

1 

3 

variable index := t. variable ualue; 

141 

181 

1 

3 

get token; 

142 

182 

1 

3 

if t. class <> assign then 

143 

183 

1 

3 

factor^value ;= var iable_tableCvar iable_index3 
else begin 

144 

185 

1 

4 

get token; 

145 

186 

1 

4 

expression(expression value); 

146 

187 

1 

4 

variable tableCvariable index! := expression value; 

147 

188 

1 

4 

factor value := expression value; 

148 

189 

1 

4 

end; 

150 

190 

1 

3 

end ; 

152 

191 

1 

2 

l_paren : begin 

152 

192 

1 

3 

get_token; 

153 

193 

1 

3 

expression (expression_value); 

154 

194 

1 

3 

factor^ualue !“ expression_value; 

155 

195 

1 

3 

if t. class = r^paren then 

156 

196 

1 

3 

get_token 

else error (missing_r_paren) ; 

158 

198 

1 

3 

end; 

160 

199 

1 

2 

int_const : begin factor_value := t . int_const_value; get_token; end; 

164 

200 

1 

2 

otherwise error ( error_in_f actor ) ; 

166 

201 

1 

2 

end (♦ case * ) ; 

168 

202 

1 

1 

end (* factor »); 

169 

204 

0 

0 

(* - - - 

procedure terRi(var tera_value ; integer); 

170 

206 

1 

0 

(« parse: <factor> C<muT_op> <factor>3.., 





var f actor_l_value : integer; 

171 

208 

1 

0 

f actor_2_value : integer; 

172 

209 

1 

0 

op : char; 

173 

210 

1 

0 

begin (« terra *) 

173 

211 

1 

1 

factor ( f actor_l_value ) ; 

174 

212 

1 

1 

while t. class = roul_op do begin 

175 

213 

1 

2 

op := t .«ul_op_vaIue ; 

176 

214 

1 

2 

get_token ; 

177 

2^5 

1 

2 

factor ( f actor_2_value ) ; 

178 

216 

1 

2 

case op of 
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Sample Program Listing 


SERIES-in Pascal-86, V2.0 
TERM 


STMT 

LINE 

NESTING 

SOURCE TEXT: ;F7;DC7.PAS 

179 

217 

1 

3 

*** ; factor 1 value := factor 1 value * factor 2 value; 

180 

218 

1 

3 

: factor 1 value := factor 1 value div factor 2 value; 

181 

219 

1 

3 

otherwise error (error in term!; 

183 

220 

1 

3 

end (♦ case ♦); 

185 

221 

1 

2 

end ; 

187 

222 

1 

1 

term value := factor 1 value; 

188 

223 

1 

1 

end (* term *) ; 

189 

225 

0 

0 

(♦ 

procedure expression (var expression value : integer); 

190 

227 

1 

0 

(« parse: C<add op>3 <terro> C<add op> <term>3... ♦) 





var term 1 value : integer; 

191 

229 

1 

0 

terra_2_value : integer; 

192 

230 

1 

0 

op : char; 

193 

231 

1 

0 

begin (♦ expression ♦) 

193 

232 

1 

1 

if t. class « add op then begin 

194 

233 

1 

2 

op := t.add op value; 

195 

234 

1 

2 

get^token ; 

196 

235 

1 

2 

end 

197 

236 

1 

i 

else op ; 

199 

237 

1 

1 

term (term 1 value); 

200 

238 

1 

1 

case op of 

201 

239 

1 

2 

'+» : (* null *); 

202 

240 

1 

2 

; term 1 value := -term 1 value; 

203 

241 

1 

2 

otherwise error(error in expression); 

205 

242 

1 

2 

end (♦ case ♦) ; 

207 

243 

1 

1 

while t. class = add_op do begin 

208 

244 

1 

2 

op s~ t .add_op_vaiue; 

209 

245 

1 

2 

get^token ; 

210 

246 

1 

2 

term (term_2_value) ; 

211 

247 

1 

2 

case op of 

212 

248 

1 

3 

: term_l_value := term_l_value + term_2_value ; 

213 

249 

1 

3 

: term^Uvalue term_l_ualue - tsr!s_2_value ; 

214 

250 

1 

3 

otherwise error (error_in_expression ) ; 

216 

251 

1 

3 

end (♦ case *) ; 

218 

252 

1 

2 

end ; 

220 

253 

1 

1 

expression^value := terro_l_value ; 

221 

254 

1 

1 

end (♦ expression *); 

222 

256 

0 

0 

(* - 

procedure statement; 

223 

258 

1 

0 

(♦ parse: <expression> <line_end> «) 





var expression_valu8 : integer; 

224 

260 

1 

0 

begin (* statement ♦) 

224 

261 

1 

1 

expression ( expression_value ) ; 

225 

262 

1 

1 

if t. class = line_end then writeln(expression_ualue; 1 ) 

226 

263 

1 

1 

else error(error_in_statement ) ; 

228 

264 

1 

1 

end statement ♦! ; 

229 

267 

0 

0 

begin (* main program ♦) 

229 

269 

0 

1 

(» initialize variable table *) 


for c ;= 'a* to do uariable_tableEc3 := 0; 
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STMT 

LINE 

NESTING 

SOURCE TEXT: :F7:DC7.PAS 

231 

272 

0 

1 

(♦ sign on ♦) 

writeln (’Desk Calculator 

232 

275 

0 

1 

(* error restart *) 
9999: 

repeat (♦ forever *) 

232 

278 

0 

2 

get_l ine ; 

233 

279 

0 

2 

get_token ; 

234 

280 

0 

2 

statement ; 

235 

281 

0 

2 

until false; 

237 

283 

0 

1 

{♦ sign off ♦) 

1000: 

writeln ( ’Exit’ ) ; 

238 

287 

0 

1 

end . 
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Sample Program Listing 


SERIES-III Pascal-86, 


Nante 


1000 . 

9999 

ADD OP 

ASSIGN 

BOOLEAN 

BUFFER ....... 

C 

C 

c 

c 

CHAR ........ 

CR 

DIGIT. ....... 

E 

EMPTY. . 

END OF LINE 

ERROR 

ERROR CLASS 

ERR0R“IN EXPRESSION. 

error"in’'factor. . . 

ERROR IN STATEMENT . 
ERRORS I N'TERM, . . . 

EXPRESSION 

EXPRESSION VALUE . . 
EXPRESSION "value . . 
EXPRESS I ON" VALUE . . 

FACTOR . 

FACTOR i VALUE . . . 
FACTOR 2 VALUE . . . 
FACTORI VALUE . . . . 

FALSE 

FULL 

GET CHAR 

GET"LINE 

GET TOKEN 

ILLEGAL TOKEN. . . . 

INPUT. 7 

INTEGER 

INT.CONST 

LF ........ . 

LINE END 

lineItoo long. . . . 

LOWER CASE . . . . . 

L PAREN 

MAX LINE LENGTH. . . 
MISSING R PAREN, . . 

MUL OP . 

OP 7 . . . 

OP 

OUTPUT 


V2.0 


Cross-Ref erence Listing 


Offset Length 


Attributes and References 


14H 

74H 

4H 

4H 

4H 


4H 


4H 

FFFCH 

FFFCH 

FFFCH 

FFFAH 

4H 


8H 


FFF9H 

FFF9H 

OH 


label in DC at 237; read: 127. 
label in DC at 232; read: 39. 

1 TOKEN CLASS constant in DC at 5; read: 7 111 193 207. 

1 TOKEN^CLASS constant in DC at 5; read: 9 121 142. 

1 primitiue type; read: 62 64 66. 

44 TEXT BUFFER variable in DC at 23; write: 42 43 44 50 51 57 58 72 77 82; 
read: 26 49 50 51 56 59 59 69 71 71 72 73 73 82. 

1 CHAR variable in DC at 22; write: 59 73 76 107 229; read; 80 83 85 89 91 95 
98 99 105 110 112 116 120 230. 

1 CHAR parameter in DIGIT at 62; read: 63 63. 

I CHAR parameter in LOWER.CASE at 66; read: 67 67. 

1 CHAR parameter in UPPER CASE at 64; read: 65 65. 

1 primitive type; read: 7"s 12 20 22 62 64 66 138 172 192. 

1 predefined CHAR constant; read: 76 105. 

BOOLEAN function in GET TOKEN at 62; write: 63; read; 95 98. 

1 ERROR CLASS parameter in ERROR at 25; read: 27. 

1 (EMPTY, ..., FULL) constant in DC at 16; read: 43 69 77. 

1 ERROR CLASS constant in DC at 4; read: 30. 

procedure in DC at 25; read: 53 122 129 157 165 182 204 215 227. 

1 (ILLEGAL TOKEN,... , ERROR IN TERM) .type in DC at 4; read: 25. 

I ERROR CLASS constant in DC at 4; read: 34 204 215. 

1 ERROR CLASS constant in DC at 4; read: 32 165. 

1 ERROR’CLASS constant in DC at 4; read: 35 227. 

1 ERRORIcLASS constant in DC at 4; reads 33 182. 

procedure in DC at 189; read: 145 153 224. 

2 INTEGER var parameter in EXPRESSION at 189; write: 220. 

2 INTEGER variable in FACTOR at 137; write: 145 153; reads 146 147 154. 

2 INTEGER variable in STATEMENT at 223; writes 224; reads 226. 

procedure in DC at 136; reads 173 177. 

2 INTEGER variable in TERM at 170; write: 173 179 ISO; reads 179 180 187. 

2 INTEGER variable in TERM at 171; write: 177; read; 179 180. 

2 INTEGER var parameter in FACTOR at 136; write; 143 147 154 160. 

1 predefined BOOLEAN constant; read: 236. 

1 (EMPTY,... , FULL) constant in DC at 16; reads 57. 

procedure in GET^TOKEN at 68; read: 81 86 92 100 119 132. 

procedure in DC at 41; read; 70 232. 

procedure in DC at 61; read; 141 144 152 156 161 176 195 209 233. 

1 ERROR_CLASS constant in DC at 4; read: 28 122 129. 

8 predefined TEXT variable; writes 47; read; 46 48 51 54. 

2 primitive type; read: 13 24 136 137 169 170 171 189 190 191 223. 

1 TOKEN_.CLASS constant in DC at 5; reads 13 96 160. 

i predefined CHAR constant; read: 107. 

1 TOKEN CLASS constant in DC at 5; reads 14 106 225. 

1 ERROR CLASS constant in DC at 4; read: 29 53. 

BOOLEAN function in GET TOKEN at 66; writes 67; read; 83. 

1 TOKEN CLASS constant in"DC at 5; read: 10 125 152. 

2 INTEGER constant in DC at 3; read; 17 18 19 20 49. 

1 ERROR CLASS constant in DC at 4; read; 31 157. 

1 TOKEN CLASS constant in DC at 5; reads 8 115 174. 

1 CHAR variable in EXPRESSION at 192; write; 194 198 208; reads 200 211. 

1 CHAR variable in TERM at 172; write; 175; reads 178. 

8 predefined TEXT variable; reads 26 28 29 30 31 32 33 34 35 38 45 226 231 
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Cross-Ref erence Listing 


237. 

R PAREN I TOKEN CLASS constant in DC at 5; read: 11 126 155. 

STATEMENT procedure in DC at 222j read; 234. 

T. ........ . 75H 3 TOKEN variable in DC at 21; write: 84 85 90 91 96 97 99 106 111 112 115 116 

121 125 126; read; 99 139 140 142 155 160 174 175 193 194 207 208 225. 

TERM procedure in DC at 169; read; 199 210. 

TERM 1 VALUE .... FFFCH 2 INTEGER variable in EXPRESSION at 190; write: 199 202 212 213; read: 202 

212 213 220. 

TERM 2 VALUE .... FFFAH 2 INTEGER variable in EXPRESSION at 191; write: 210; read: 212 213. 

TERM^VALUE 4H 2 INTEGER var parameter in TERM at 169; write; 187. 

TEXT^BUFFER. .... 44 record type in DC at 16; read: 23, 

TOKeR. ....... 3 record type in DC at 6; read: 21. 

TOKEN CLASS 1 (ADD OP, . . . ,LINE_END) type in DC at 5; read: 6. 

UPPER CASE BOOLEAN function in GET TOKEN at 64; write: 65; read: 89. 

VARIABLE 1 TOKEN CLASS constant in DC at 5; read; 12 84 90 140. 

VARIABLE INDEX . . . FFFBH 1 CHAR variable in FACTOR at 139; write: 140; read: 143 146. 

VARIABLE TABLE ... 40H 52 array! 'a' .. 1 of INTEGER variable in DC at 24; write: 146 23Q-; read: 

143. 


Summary Information: 


PROCEDURE 

OFFSET 

CODE 

SIZE 

DATA 

SIZE 

STACK 

SIZE 

ERROR 

00C8H 

014CH 

332D 



OOOEH 

14D 

GET LINE 

0214H 

OOBEH 

190D 



0012H 

18D 

GET TOKEN 

0399H 

0147H 

327D 



0008H 

8D 

DIGIT 

02D2H 

002CH 

44D 



0008H 

8D 

UPPER CASE 

02FEH 

002CH 

44D 



0008H 

SD 

LOWER CASE 

032AH 

002CH 

44D 



0008H 

8D 

GET CHAR 

0356H 

0043H 

67D 



0008H 

8D 

FACTOR 

04E0H 

00B4H 

180D 



OOOEH 

14D 

TERM 

0594H 

007BH 

123D 



001 OH 

16D 

EXPRESSION 

060FH 

00B7H 

183D 



001 OH 

16D 

STATEMENT 

06C6H 

0036H 

54D 



OOOCH 

12D 

DC 

06FCH 

00E7H 

231D 

0078H 

120D 

OOOEH 

14D 

-CONST IN CODE- 


00C8H 

200D 





Total 


07E3H 

2019D 

0078H 

120D 

00C4H 

196D 


287 Lines Read. 

0 Errors Detected. 

447, Utilization of Memory. 
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APPENDIX F 
PSCOPE GRAMMAR 


This appendix contains the grammar that describes the syntax of PSCOPE’s com- 
mand language. “Notational Conventions” in the Preface to this manual explains 
the notational conventions used. 

Note that the command line is the unit in which PSCOPE commands are 
processed. Hence, the symbol command- line is the start symbol of the grammar. 


PSCOPE Grammar 


command-line ::= [commandl [; command]* 

command asm-command 
\ base-command 
I callstack-command 
\count-command 
I define-command 
I directory-command 
I display-command 
I do-command 
I edit-command 
\eval-command 
I exit-command 
\go-command 
I help-command 
I if-command 
I inputmode-command 
I include-command 
I list-command 
I load-command 
I modify-command 
\port-command 
\put-command 
\remove-command 
I repeat-command 
\return-command 
I step-command 
I view-command 
I write-command 

asm-command ::= ASM ADDRESS = 'assembler-mnemonic 

' [,' assembler-mnemonic] * 

|SASM ADDRESS = 'assembler-mnemonic 

'[,' assembler-mnemonic]* 

I ASM ADDRESS [/engf/7-spec] 

jSASM ADDRESS [/engf/?-spec] 

base-command = BASE [=expr] 

callstack-command ::== CALLSTACK lexpr] 
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count-command — COUNT expr 

[loop-command]* 

end-count 

loop-command :■. = WHILE expr 
I UNTIL expr 
I [command] 

end-count ENDCOUNT 
|END 

define-command :: = DEFINE BRKREG name = break-group [, break-group]* 
IDEFINETRCREG name = break-group [, break-group]* 

I DEFINE PATCH expr [TIL expr] = patch-value 
I DEFINE PROC name = command 
I DEFINE LITERALLY name = string [string]* 

[DEFINE [GLOBAL] mtype name [= expr] 

break-group ::= (break-point [, break-point]*) [CALL proc-name] 

I break-point [CALL proc-name] 

break-point expr 

patch-value :: = command 
[NOP 

directory-command :.= DIR [directory] [directory-type] 

directory DEBUG 
[PUBLIC 
I ; module-name 

directory-type = mtype 
\ dtype 
[PATCH 
[ARRAY 

[ENUMERATION 

[FILE 

[LABEL 

[LINE 

[MODULE 

[PROCEDURE 

[RECORD 

[SET 

display-command ■.:= PROC proc-name 

[LITERALLY literally-name 
i BRKREG brkreg-name 
[TRCREG trcreg-name 
[PATCH expr 

I mtype address [length-spec] 

\expr 

[REGS 

length-spec ::= LENGTH expr 
[to expr 

do-command : : = DO 

[command]* 

END 
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edit-command = EDIT [edit-item] 

edit-item ::= name 

I PATCH expr 
|GO 

eval-command EVAL expr[eval-type] 

eval-type :;= LINE 

I PROCEDURE 
jSYMBOL[ALL] 

exit-command :: = EXIT 

go-command GO [break-spec]* 

|GO FOREVER 

break-spec ::= USING brkreg-item [, brkreg-item]* 
I TIL expr[, expi]* 

brkreg-item ::= BRKREG 
I brkreg-name 
ITRCREG 
I trcreg-name 

heip-command ::= HELP [name] 

if-command ::= IF expr THEN 

[command]* 

[ORIF expr THEN 
[command]*]* 

[ELSE 

[command]*] 

end-if 

end-if::= ENDIF 
|END 


include-command ■.:= INCLUDE pafftna/ne [NOLIST] 

inputmode-command ;;= INPUTMODE [=N] 

list-command ::= LIST [pathname] 

INLIST 

load-command = LOAD pathname [load-option]* 
[CONTROLS controls-text] 

load-option ::= NOLINES 

I NOSYMBOLS 

ICH8087 /*foriRMX*/ 

IE8087 /*for Series Ill/Series IV*/ 

port-command : PORT port-# expr [= expr] 

jWPORT port-# expr[=expr] 

modify-command ::= variable = expr 

I mtype address [length-spec] = modify-list 
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modify-list :\ = expr[, expr]» 

I mtype address [length-spec] 

length-spec :: = LENGTH expr 
I TO expr 

put-command ::= PUT pathname put-Ust 
I APPEND pathname put-Ust 

put-list = put-item [, put-item]* 

I DEBUG 

put-item mtype 
I dtype 
I name 

I PATCH [expr] 

remove-command ::= REMOVE remove-item [, remove-item]* 
IREMOVE DEBUG 

remove-item ::= mtype 
I dtype 
I name 

I PATCH [expr] 

repeat-command :\= REPEAT 

[loop-command] * 
end-repeat 

loop-command ::= WHILE expr 
1 UNTIL expr 
{[command] 

end-repeat :: = ENDREPEAT 
lEND 

return-command ::= RETURN [expr] 

step-command :: = LSTEP 
IPSTEP 
jlSTEP 

view-command ■.: = VIEW view-item 

view-item fiie-name 

write-command ::= WRITE 

[USING istring-expr)] 

[expr I expr]*] 

expr : : = iogic-term [or-op iogic-term] * 

or-op ::= OR 
|XOR 

logic-term ::= /og/c-facfor [AND logic-factor]* 
logic-factor :■. = [NOT] logic-primary 

logic-primary : : = arith-expr [relational-op arith-expr] 
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relational-op < 

\> 


l<> 

arith-exp Imtype] address 
address ::= term [add-op term]* 
add-op ::== + 

1 / 

I MOD 

term ::= factor[mult-op factor]* 

factor = [add-op] primary 

primary ::= primitive [: primitive] 

primitive ::= iexpr) 

I variable 
\ value 

variable ::= symbolic-reference 
I mtype-variable-name 
1 $ 

I BASE 

INAMESCOPE 
j reg-name 

symbolic-reference ::= [: module-name .] 

symbol [qualifier]* 
I [; module-name] 

* line-number 


Isymbol ::= ["] name 

qualifier = left-bracket expr[, expr]* 
right-bracket 
|. symbol 

I! 

left-bracket :: = [ 
right-bracket = ] 
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reg-name AX 

/* foriRMX only */ 

IBX 

ISTO 

lex 

ISTI 

|DX 

|ST2 

IBP 

|ST3 

ISP 

IST4 

|DI 

|ST5 

ISI 

IST6 

Ics 

IST7 

Ids 

|FIA 

|ES 

IFIO 

ISS 

IFCW 

IIP 

FDA 

i FLAGS 


|AL 


lAH 


IBL 


|BH 


ICL 


ICH 


IDL 


|DH 


IFL 


IFH 



value :. = integer-constant 
\real-constant 
I Boolean-constant 
I string-constant [string-constant]* 
\proc-name [{expri, expr]*)] 

I % actual-parameter 
isUBSTR (string-expr, expr, expr) 
ICONCAT [string-expr[, string-expi]*) 
jSTRLEN (string-expr) 

ICI 

I ACTIVE (symbolic-reference) 

I . symbolic-reference 
ISELECTOROF (expr) 

I OFFSETOF (expr) 

I actual-parameter : : = integer-constant 
(expr) 

NP 


dtype::= LITERALLY 
IBRKREG 
ITRCREG 
iPROC 
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mtype ::= BOOLEAN 
ICHAR 
I BYTE 
iWORD 
IDWORD 
lADDRESS 
[SELECTOR 
[POINTER 
[SHORTINT 
[INTEGER 
[LONGINT 
[EXTINT 
[BCD 
[REAL 
[LONGREAL 
[TEMPREAL 
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APPENDIX G 
RESERVED KEYWORDS 



This appendix contains the keywords PSCOPE recognizes and uses. You cannot 
use keywords as user-defined object names. To reference a program symbol whose 
name is the same as a PSCOPE keyword, you must prefix the symbol with a quota- 
tion mark ("), as discussed in Chapter 3. PSCOPE also recognizes special operators 
and delimiters which, like the reserved keywords, you cannot use in any other 
way. PSCOPE reports all attempts to incorrectly use a PSCOPE keyword or delimi- 
ter as syntax errors. 


PSCOPE Keywords 


A 

ACTIVE 

ADDRESS 

AFL 

AH 

AL 

ALL 

AND 

APPEND 

ARRAY 

ASM 

AX 

BASE 

BCD 

BH 

BL 

BOOLEAN 

BP 

BRKREG 

BX 

BYTE 

CALL 

CALLSTACK 

CFL 

CH8087 

CH 

CHAR 

Cl 

CL 

CONCAT 

CONTROLS 

COUNT 

CS 

CX 

DEBUG 

DEFINE 

DEL 

DH 

DI 

DIR 

DL 

DO 

DS 

DWORD 

DX 

E8087 

EDIT 

ELSE 

END 

ENDCOUNT 

ENDIF 

ENDREPEAT 

ENUMERATION 

ES 

EVAL 

EXIT 

EXTINT 

FALSE 

FCW 

FH 

FDA 

FIA 

FILE 

FIO 

FL 

FLAG 

FOREVER 

FSW 

GLOBAL 

GO 

HELP 

IF 

IFL 

INCLUDE 

INPUTMODE 

INTEGER 

IP 

ISTEP 

LABEL 

LENGTH 

LINE 

LIST 

LITERALLY 

LOAD 

LONGINT 

LONGREAL 

LSTEP 

MOD 

MODE 

MODULE 

NAMESCOPE 

NOCODE 

NOLINES 

NOLIST 

NOSYMBOLS 

NOP 

NOT 

NP 

OFFSETSOF 

OFFSETOF 

OFL 

OR 

ORIF 

PATCH 

PFL 

POINTER 

PORT 

PROC 

PROCEDURE 

PSTEP 

PUBLIC 

PUT 

REAL 

RECORD 

REGS 

REMOVE 

REPEAT 

RETURN 

SASM 

SELECTOR 

SELECTORSOF 

SELECTOROF 

SET 

SFL 

SHORTINT 

SI 

SP 

SS 

STO 

STl 

ST2 

ST3 

ST4 

STS 

ST6 

ST7 

STRLEN 

SUBSTR 

SYMBOL 

TEMPREAL 

TFL 

THEN 

TIL 

TO 

TRACEACT 

TRACEREGS 

TRCREG 

TRUE 

UNTIL 

USING 

VIEW 

VSTB 

VSTBUFFER 

WRITE 

WHILE 

XOR 

WORD 

ZFL 

WPORT 
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Reserved Keywords 


PSCOPE Operators and Delimiters 

;,:$''!=.[]()% 
<= < > >= <> = = + - * / 
/% %/ 
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APPENDIX H 
PSCOPE COMMAND INDEX 


This appendix lists each PSCOPE command and refers you to the section in this 
manual where you can find more information. 


Command Page 

% 8-3 

ACTIVE 5-11 

APPEND 7-6 

ASM 5-13 

BASE 10-9 

B(lock) 2-11 

BRKREG 11-1 

call debug procedures 8-2 

CALLSTACK 10-4 

change 8086/8088 flags 5-5 

change 8086/8088 registers .... 5-7 

change 8087 register 5-8 

change NAMESCOPE 5-10 

change program symbol 5-5 

Cl 10-13 

CONCAT 10-13 

COUNT 6-1 

CRT 2-1 

debug procedure calls 8-2 

debug procedure parameters ... 8-3 

debug procedure return 8-2 

D(elete) 2-11 

DEFINE 7-2 

DErINti debug procedure .... 8-1 

DIR 10-2 

DISPLAY 7-3 

display debug objects 7-3 

display memory 5-11 

display program symbol 5-3 

DO 6-3 

EDIT 2-8 

EVAL 10-7 

EXIT 10-1 

fully qualified reference 5-1 

G(et) 2-11 

GO 4-2,11-4 

HELP 10-5, A-1 

IF 6-2 


Command Page 

INCLUDE 10-6 

INPUTMODE 10-10 

I(nsert) 2-11 

ISTEP 4-4 

line number reference 3-3 

LIST 10-6 

LOAD 4-1 

LSTEP 4-3 

MACRO 2-2 

memory reference 3-9 

MODIFY 7-5 

modify memory 5-12 

modify debug symbol 7-5 

NAMESCOPE 5-1,5-10 

NOCRT 2-1 

NOLIST 10-6 

NOMACRO 2-2 

NOSUBMIT 2-3 

OFFSETSOF 10-15 

PATCH 9-1 

PSTEP 4-3 

PUT 7-6 

Q(uit) 2-12 

REGS 5-8 

read and write I/O ports 5-9 

REPEAT 6-1 

REMOVE 7-5 

RUN 2-1 

SASM 5-13 

SELECTORSOF 10-15 

SLA 5-15 

STRLEN 10-13 

SUBMIT 2-3 

SUBSTR 10-13 

symbolic reference 3-9 

TRCREG 11-3 

V(iew) 2-12, 2-13 
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Command Page 

VSTBUFFER 2-4 

WRITE 10-12 

X (change) 2-12 
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APPENDIX I 
PSCOPE UNDER THE IRMX™ 
OPERATING SYSTEM 


PSCOPE runs on any 86/3xx microcomputer system running the iRMX-86 operat- 
ing system, release 5 or greater. PSCOPE requires at least 11 OK bytes of user 
memory. Your application program requires additional memory. 

The following major iRMX-86 subsystems must be present. 

Nucleus 

Basic I/O system 
Extended I/O system 
Human interface 
Application loader 

Universal Development Interface (UDI) 

When running under the iRMX-86 operating system, PSCOPE differs in the fol- 
lowing arsHs. 

Linking 
Invocation 
Multitasking support 
8087 support 
CNTL-C limitation 


Linking 

Be sure to use the link library files supplied with the iRMX-86 operating system. 

When invoking link86, include the following two options during the final link. 

SEGSIZE (STACK ( -H 2048) ) 

MEMPOOL ( -I- 2500,0FF000H) 

invocation 

Because systems that run iRMX-86 are 8086-based, you do not use the RUN pro- 
gram to invoke PSCOPE. A typical invocation line is as follows: 


pathname PSCOPE.86 options 
Where: 

pa thname specifies the path of the file back to the root directory. 

For example, /user/world/prog/pscope.86 means that PSCOPE is a file in the 
directory prog which itself is in the directory world which itself is in the directory 
user which is a directory under the root. 
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Multitasking Support 

Although the iRMX-86 operating system handles multiple tasks, PSCOPE can 
only debug one task at a time. PSCOPE has no cognizance of tasks initiated by the 
task being debugged. 

Because PSCOPE directly manipulates the iRMX-86 interrupt vector table, no 
other task may manipulate the interrupt vector table while PSCOPE is running. 
When you invoke PSCOPE, PSCOPE saves the interrupt vector table. When you 
exit PSCOPE, PSCOPE restores the interrupt vector table. The consequence of 
this is that in a multi-station system, only one station at a time may run PSCOPE. 

If PSCOPE hangs, you cannot be sure of what the interrupt vector table may hold. 
Reboot the system to return the interrupt vector table to a known state. 


8087 Support 

If the program you want to debug performs real arithmetic, the microcomputer 
system must contain the iSBC 337 MULTIMODULE (8087 hardware). You 
cannot use the 8087 software emulator. 

When you load your program with the LOAD command, include the CH8087 
option, as in the following example: 

«LOAD pager.86 CH8087 


other Resources Required 

The debugger requires the following additional host resources: 

• The software interrupt 3 (the one-byte, debugger-oriented INT instruction) . 

• The trap flag and interrupt 1 (used for single-stepping) . 

• The CNTL-C trap (system call DQ$TR AP$CC) . 

Your program should not use these host system resources. 

In addition, PSCOPE uses interrupts 0, 4, 5, 16, 17, and 20 through 31 for error 
handling and floating point operations. However, your program can use these in- 
terrupts since PSCOPE maintains separate copies of these interrupt vectors for 
itself and your program. 
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&, 2-6, 3-1 
$,3-2,11-5 
%, 8-3 

Accessing debug procedure parameters, 8-3, 8-4 
ACTIVE function, 5-1 1 
ADDS Regent Model 200 (2400 baud only) 
configuration, B-5 

ADDS Viewpoint 3 A Plus configuration, B-6 
APPEND command, 7-6 thru 7-8 

BASE command, 10-9, 10-10 
BLOCK command, 2-11, 2-12 
Break registers, 11-1 thru 11-3 
Beehive Mini-Bee configuration, B-7 
Breakpoints, 11-1 thru 11-7 
BRKREG command, 11-1 thru 11-3 

Calling debug procedures, 3-11, 8-2 

Calling sequence, see CALLSTACK command 

CALLSTACK command, 10-4, 10-5 

Change 8086/8088 flags, 5-5, 5-6 

Change 8086/8088 registers, 5-7, 5-8 

Change 8087 registers, 5-8, 5-9 

Change name scope, 5-10, 5-11 

Change program symbol, 5-5 

Character string constants, 3-4, 3-5 

Cl command, 10-13 thru 10-15 

Code patch display, 9-2, 9-3 

Code patches, 9-1 thru 9-3 

Command entry, 2-6 

Command index, H-1, H-2 

Commands, see PSCOPE commands 

Comments, 3-6 

Compile restrictions, 1-2 

CONCAT command, 10-13 thru 10-15 

Configuration commands, B-1 thru B-3 

Configuration 

ADDS Regent Model 200 (2400 baud only), B-5 

ADDS Viewpoint 3A Plus, B-6 

Beehive Mini-Bee, B-7 

DECVT52, B-8 

DEC VTIOO, B-9 

Hazeltine 1420, B-10 

Hazeltine 1510 (Tilde Lead-in), B-11 

Hazeltine 1510 (ESC Lead-in), B-12 

Intel Series IIIE,B-13 

Lear Siegler ADM-3A, B-14 

Tele video 910 Plus, B-1 5 

Televideo 925 and 950, B-16 

Zentec, B-1 7 

Configuring PSCOPE for non-Intel 
terminals, B-1 thru B-1 7 
Constants, 3-9 


Continuation flags 
&, 2-6, 3-1 
!,2-9 

Control constructs 
COUNT, 6-1, 6-2 
DO, 6-3 
IF, 6-2, 6-3 
REPEAT, 6-1, 6-2 
COUNT control construct, 6-1, 6-2 
CRT invocation control, 2-1, 2-2 
Current name scope, 5-1 thru 5-3 
Cursor control keys (for edit) , 2-6, 2-7, 2-9 thru 2-11 

DEC VT52 configuration, B-8 
DEC VTIOO configuration, B-9 
Debug objects, 7-1, 7-2 
debug type, 7-2 
memory type, 7-2 
Debug parameter reference, 3-11 
Debug procedure calls, 3-11, 8-2 
Debug procedure definitions, 8-1 
Debug procedure parameter access, 8-3, 8-4 
Debug procedure return, 8-2, 8-3 
Debug session example, 1-6 thru 1-18 
Debug symbol object types, 3-3 
Debug symbols, 3-2 
Debug type debug objects, 7-2 
Debug variable references, 3-10 
Debugger invocation, 2-1 

Debugging session termination, see EXIT command 
DEC VT52 configuration, B-8 
DEC VTIOO configuration, B-9 
DEFINE BRKREG command, 11-1 thru 11-3 
DEFINE code patches, 9-1, 9-2 
DEFINE command, 7-2, 7-3, 8-1 
DEFINE debug procedures, 8-1 
DEFINE PATCH command, 9-1, 9-2 
DEFINE PROC command, 8-1 
DEFINE TRCREG command, 11-3, 11-4 
DELETE (D) command, 2-12 
Delimiters, 3-1, G-2 
DIR command, 10-2 thru 10-4 
Directory command, see DIR command 
Display code patch, 9-2, 9-3 
DISPLAY command, 7-3, 7-4 
Display information at the terminal, 
see WRITE command 
Display memory, 5-11, 5-12 
Display program symbol, 5-3, 5-4 
DO control construct, 6-3 

EDIT command, 2-8 
Editor display, 2-9 

Editor, see internal screen-oriented editor 
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End a debugging session, see EXIT command 
Enter PSCOPE commands, 2-1, 2-2 thru 2-6 
Error messages, A-1 thru A-7 
Error messages, invocation, A-1 
Errors in syntax, 2-7 

ESC key to invoke the internal editor, 2-8 
EVAL command, 10-7 thru 10-9 
Evaluating expressions, see EVAL command 
Example PSCOPE debug session, 1-6 thru 1-18 
Exception trapping, 11-6, 11-7 
Execute user program, see GO command 
EXIT command, 10-1, 10-2 
Explicit typing of memory references, 
see memory references with explicit typing 
Expression evaluation, see EVAL command 
Expressions, 3-8 

Fatal errors, A-1 

Floating point numbers, 3-4 

Fully qualified line references, 5-1 thru 5-3 

Fully qualified name, 5-1 thru 5-3 

Fully qualified references, 5-1 thru 5-3 

Further reading, vi, vii 

GET (G) command, 2-12 
Global debug objects, 7-1 
GO command, 4-2, 4-3, 11-4 thru 11-6 
Grammar, PSCOPE, F-1 thru F-7 

Hazeltine 1420 configuration, B-10 

Hazeltine 1510 (Tilde Lead-in) configuration, B-11 

Hazeltine 1510 (ESC Lead-in) configuration, B-12 

HELP command, 10-5, 10-6, A-1 

Host system execution environment, 1-2 

IF control construct, 6-2, 6-3 
INCLUDE command, 10-6, 10-7 
Index of PSCOPE commands, H-1 
INPUTMODE command, 10-10 thru 10-12 
iRMX information, I-l 
INSERT (I) command, 2-12, 2-13 
Integers, 3-3, 3-4 

Intellec Series III information, C-1 
Intellec Series IV information, D-1 
Intel Series III E configuration, B-13 
Internal errors, A-1 

Internal screen-oriented editor, 2-7 thru 2-11 
Cursor control, 2-9 thru 2-11 
Commands, 2-9 
Display, 2-9 
Entering, 2-8 
Exiting, 2-8 

Invocation controls, 2-1 thru 2-5 
CRT|NOCRT,2-l,2-2 
MACRO I NOMACRO, 2-2, 2-3 
NOSUBMIT I SUBMIT, 2-3 
VSTBUFFER, 2-4 
Invocation error messages, 2-4, 2-5 
Invoking the debugger, 2-1 


ISTEP command, 4-4 
Keys 

Cursor control during edit, 2-9 thru 2-1 1 
Line editing, 2-6, 2-7 
Keywords, 3-2, 3-3, G-1 

Lear Siegler ADM-3A configuration, B-14 

Line editing keys, 2-6, 2-7 

Line number references, 3-3, 3-10 

Line numbers, 3-3 

LIST command, 10-6 

Listing file, see LIST command 

LOAD command, 4-1, 4-2 

Local debug objects, 7-1 

LSTEP command, 4-3, 4-4 

Machine register references, 3-9 

MACRO invocation control, 2-2, 2-3 

Memory display, 5-11,5-12 

Memory modification, 5-12, 5-13 

Memory references with explicit typing, 3-9, 3-10 

Memory symbol object types, 7-5, 7-6 

Memory type debug objects, 7-2 

Memory type differences, 3-7 

Menu commands, see PSCOPE menu commands 

MODIFY command, 7-5 

Modify memory, 5-12 thru 5-14 

Name scope, 5-1 thru 5-3 
Name scope change, 5-10, 5-11 
Names, 3-2, 3-3 

NOCRT invocation control, 2-1, 2-2 
NOLIST command, 10-6 
NOMACRO invocation control, 2-2, 2-3 
NOSUBMIT invocation control, 2-3 
Notational conventions, vii, viii 
Number base, see BASE command 
Numeric constants, 3-3, 3-4 

Object file, 7-6 thru 7-8 
OFFSETSOF command, 10-15 
Operands, 3-8 thru 3-11 
Operators, 3-5, 3-11, 3-12, G-2 
OPTIMIZE (O) compiler option, 1-2 thru 1-4 

Parameter accessing, 8-3, 8-4 
Parameter references, 3-11 
Partially qualified line references, 3-3, 5-3 
Pascal program example, 
see sample PSCOPE debug session 
PATCH command, 9-1 thru 9-3 
Patch definition, 9-1, 9-2 
Patch removal, 9-3 
PL/M program example, 
see example PSCOPE debug session 
Precedence of operators, see operators 
PROC command, 8-1 
Procedure calls, 3-11, 8-2 
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Product definition, 1-1 

Program, development process, 1-1, 1-2 

Program example, E-1 thru E-8 

Program execution, see GO command 

Program symbol change, 5-5 

Program symbol display, 5-3, 5-4 

Program symbol references, 3-9, 5-1 thru 5-3 

Program symbols, 3-2 

PSCOPE command entry, 2-6 

PSCOPE command index, H-1 

PSCOPE commands 

Accessing debug procedure parameters, 8-3, 8-4 

ACTIVE, 5-11 

APPEND, 7-6 thru 7-8 

ASM, 5-13 thru 5-19 

BASE, 10-9, 10-10 

BLOCK, 2-11, 2-12 

BRKREG, 11-1 thru 11-3 

CALLSTACK, 10-4, 10-5 

Change name scope, 5-10, 5-1 1 

Change program symbol, 5-5 

Change 8086/8088 flags, 5-5, 5-6 

Change 8086/8088 registers, 5-7, 5-8 

Change 8087 registers, 5-8, 5-9 

Cl, 10-13 thru 10-15 

CONCAT, 10-13 thru 10-15 

COUNT construct, 6-1, 6-2 

Debug procedure calls, 8-2 

Debug procedure return, 8-2, 8-3 

DEFINE, 7-2, 7-3 

DEFINE BRKREG, 11-1 thru 11-3 

DEFINE debug procedure, 8-1 

DEFINE PATCH, 9-1, 9-2 

DEFINE PROC, 8-1 

DEFINE TRCREG, 11-3,11-4 

DELETE, 2-12 

DIR, 10-2 thru 10-4 

DISPLAY, 5-11, 5-12, 7-3, 7-4 

Display PATCH, 9-2, 9-3 

Display program symbol, 5-3, 5-4 

DO construct, 6-3 

EDIT, 2-8 

EVAL, 10-7 thru 10-9 
Exception trapping, 11-6, 11-7 
EXIT, 10-1, 10-2 

Fully qualified references, 5-1 thru 5-3 
GET, 2-12 

GO, 4-2, 4-3, 11 -4 thru 11-6 
HELP, 10-5, 10-6, A-1 
IF construct, 6-2, 6-3 
INCLUDE, 10-6, 10-7 
INPUTMODE, 10-10 thru 10-12 
INSERT, 2-12, 2-13 
ISTEP, 4-4 
LIST, 10-6 
LOAD, 4-1, 4-2 
LSTEP,4-3,4-4 
MODIFY, 5-12, 5-13, 7-5 
NOLIST, 10-6 


OFFSETSOF, 10-15 
PATCH, 9-1 thru 9-3 
PROC, 8-1 
PSTEP, 4-3, 4-4 
PUT, 7-6 thru 7-8 
QUIT, 2-13 

Read and Write I/O ports, 5-9, 5-10 
REGS, 5-8 
REMOVE, 7-5, 7-6 
REMOVE PATCH, 9-3 
REPEAT construct, 6-1, 6-2 
SASM, 5-13 thru 5-19 
SELECTORSOF, 10-15 
STRLEN, 10-13 thru 10-15 
SUBSTR, 10-13 thru 10-15 
TRCREG, 11-3, 11-4 
VIEW, 2-13 thru 2-15 
WRITE, 10-12, 10-13 
XCHANGE, 2-13 
PSCOPE constructs 
COUNT, 6-1, 6-2 
DO, 6-3 
IF, 6-2, 6-3 
REPEAT, 6-1, 6-2 
PSCOPE controls 
CRT, 2-1, 2-2 
Invocation, 2-1 
MACRO, 2-2, 2-3 
NOCRT, 2-1, 2-2 
NOMACRO, 2-2, 2-3 
NOSUBMIT, 2-3 
SUBMIT, 2-3 
VSTBUFFER, 2-4 

PSCOPE debug session example, 1-6 thru 1-18 
PSCOPE delimiters, G-2 
PSCOPE directory, 10-2 thru 10-4 
PSCOPE grammar, F-1 thru F-7 
PSCOPE menu commands 
BLOCK (B), 2-11, 2-12 
DELETE (D), 2-12 
GET (G),2-12 
INSERT (I), 2-12, 2-13 
QUIT (Q),2-13 
VIEW (V), 2-13 thru 2-15 
XCHANGE (X),2-13 
PSCOPE operators, G-2 
PSCOPE reserved keywords, G-1 
PSCOPE.CRTfile, 2-8 
PSCOPE.MAC file, 2-2 
PSTEP command, 4-3, 4-4 
PUT command, 7-6 thru 7-8 

QUIT (Q) command, 2-13 

Related publications, vi, vii 
Read and write I/O ports, 5-9, 5-10 
Referencing names, 3-2, 3-3 
Referencing program symbols, 
see program symbol reference 
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Registers 

Break, 11-1 thru 11-3 
Trace, 11-3, 11-4 
Remove code patch, 9-3 
REMOVE command, 7-5, 7-6 
REMOVE PATCH command, 9-3 
REPEAT control construct, 6-1, 6-2 
Reserved keywords, G-1 
Returning from a debug procedure, 8-2, 8-3 
RUN command, C-4 

Sample Pascal program, 
see sample PSCOPE debug session 
Sample PL/M-86 program, 
see sample PSCOPE debug session 
Sample PSCOPE debug session, 1-7 thru 1-18 
Screen-oriented editor, 
see internal screen-oriented editor 
SELECTORSOF command, 10-15 
Series III information, C-1 
Series IV information, D-1 
Severe errors, A-1 
SLA, see single-line assembler 
Single-line assembler, 5-13 thru 5-17 
Single-line disassembler, 5-13 thru 5-17 
Single-stepping through a program, 4-3, 4-4 
Stepping commands, 

see the ISTEP, LSTEP, and PSTEP commands 
String constants, 3-9 
String functions 
Cl, 10-13 thru 10-15 
CONCAT, 10-13 thru 10-15 
STRLEN, 10-13 thru 10-15 
SUBSTR, 10-13 thru 10-15 
STRLEN command, 10-13 thru 10-15 
SUBMIT file, 2-3 
SUBMIT invocation control, 2-3 
SUBSTR command, 10-13 thru 10-15 
Symbol object types, 3-6 

Symbol references, see program symbol references 
Symbol table, 3-6 


Syntax errors, 2-7 

Syntax notation conventions, vii, viii 

Televideo 910 Plus configuration, B-15 
Televideo 925 and 950 configuration, B-16 
Terminate debugging session, 2-6 
Tested configurations, B-4 thru B-17 
Tokens, 3-1 thru 3-6 
Trace registers, 11-3, 11-4 
Tracepoints, 11-3 thru 11-6 
Trapping exceptions, 11-6, 11-7 
TRCREG command, 11-3, 11-4 
Type conversions, 3-12, 3-13 
for expressions, 3-13 
for assignments, 3-13 

Unprintable characters, 2-9 
User symbol object types, 3-6 
Utility commands, 10-1 thru 10-13 
BASE, 10-9, 10-10 
CALLSTACK, 10-4, 10-5 
DIR, 10-2 thru 10-4 
EVAL, 10-7 thru 10-9 
EXIT, 10-1,10-2 
HELP, 10-5, 10-6, A-1 
INCLUDE, 10-6, 10-7 
INPUTMODE, 10-10 thru 10-12 
LIST, 10-6 
NOLIST, iO-6 
WRITE, 10-12, 10-13 

VIEW command, 2-13 thru 2-15 

Virtual symbol table, see VSTBUFFER invocation control 
VSTBUFFER invocation control, 2-4 

Warnings, A-1 

WRITE command, 10-12, 10-13 
XCHANGE (X) command, 2-13 
Zentec configuration, B-17 


Index-4 



ie Single Line Assembler/Disassembler 


ASM address [LENGTH expr 
TO address ] 

(ASM address = 'assembler-mnemonic'l, assembler-mnemonic] 

SASM) 


3COPE Memory Types 


ADDRESS 

BCD 

BOOLEAN 

BYTE 

CHAR 

DWORD 

EXTINT 

INTEGER 

LONGINT 

LONGREAL 

POINTER 

REAL 

SELECTOR 

SHORTINT 

TEMPREAL 

WORD 
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»COPE Operations 


AND 

Logical AND 

MOD 

Modulo 

NOT 

Logical NOT 

OR 

Logical OR 

XOR 

Logical exclusive OR 

* 

Multiplication 

— 

Negation or subtraction 

+ 

Identity or addition 

1 

Division 

= — 

Boolean equality 

< > 

Inequality 

> 

Greater than 

< 

Less than 

> = 

Greater than or equal 

< = 

Less than or equal 
The address of 

o 

Bracketing 

[] 

Array indexing 

= 

Assignment 
Pointer constructor 
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How to Use This Card 


Removing Debug Objects 


String Commands 


Hatics Italics indicate a generic term. Replace it with a user-defined symbol, a 
PSCOPE keyword, or other system-defined term. 


REMOVE \mBm 0 ry-typ 9 {.momory-type 
dBbuQ-type .debug- type 
PATCH address .PATCH address 
debug-object-name ] , debug-object-name] * 


CONCAHsIrfng-speclstring-spec]) 

C\ 

STRLENistring-spec) 


( 1 Brackets indicate an option You may or may not enter one of the 

choices set off by brackets. Do not type the brackets. 


Entering Emulation 


S\JBSTR{stnng-sp«c,starUength) 

Utility Commands 


{ I Braces indicate a required choice. You must choose one of the choices 

set off by the braces. Do not type the braces. 

* An asterisk after a set of brackets means that you can make multiple 

choices from within the brackets or repeat your choice. Do not type the 
asterisk. 

Any other symbols (parentheses or commas) are to be considered as part of the 

command. 

Invoking and Exiting PSCOPE 

lIpafhnamelPSCOPE 86 [CRT (MACRO [SUBMIT [VSTB{dec/ma/-numb®r)) 


GO (TIL break-ptlbreak-pt]* 

USING \ break-register-name 
trac 0 -register-n,ime 
6RKREG 
TRCREG 
FOREVER 


Ibreak-regisier-name 

jrace-register-name 

.BRKREG 

.TRCREG 1*1 

1 


ISTEP 


PSTEP 

LSTEP 


RUNlpal/mamalPSCOPE} NOCRT) NOMACRO) NOSUBMIT) 
EXIT 


Displaying Debug Objects, Program Variables, and Registers 

BRKREG break-register-namo 


File Handling Commands 


TRCREG trace-register-name 
name 


APPEND pathname Imemory-type [.memory-type 
debug-type .debug-type 

PATCH address .PATCH address 
debug-obiect-name] .debug-object-name]* 


memory-type {address (LIINGTH expr 
name } TO address ) 


PATCH address 


INCLUDE pathname [NOLISTl 


REGS 



LIST [pathname] 







8086/8088 Registers; 


LOAD pathname [E8087 

[CONTROLS command-fai/1 




CH8087 


AX 

cx 

CS 

NOLINES 


AH 

CH 

DS 

NOSYMBOLS] 


AL 

CL 

ES 



BX 

DX 

SS 

NOLIST 


BH 

DH 

SP 

PUT pathname [memory-type 

[.memory-type 

BL 

DL 

IP 

debug -type 

.debug- type 




PATCH address 

.PATCH address 




debug-object-name] .debug-object-name]* 

8087 Registers: 





STO 

ST4 

FSW 

Defining Debug Registers 


STl 

STS 

FCW 



ST3 

ST6 

FIA 

DEFINE BRKREG name=‘ break-pt [CALL proc-name] [.break-pt [CALL proc-name]]* 

ST4 

ST7 

FDA 


Dl 

SI 


FIO 


Sl-expd 

ACTIVE (symohc-reference) 

BASEJ“expd 

CALLSTACK [expr] 

DIR [DEBUG [memory-type 

PUBLIC debug-type 

module-name) user-type ] 

EDIT [debug-object-name 
GO 

PATCH address 

CNTL -A Deletes line to right of cursor. 

CNTL-C Cancels current editing command. 

CNTL -F Deletes character at the cursor position. 

CNTL -X Deletes line to left of cursor. 

CNTL-Z Deletes current line. 

HOME Moves cursor to left/right of line after lefl/right arrow. 

RUBOUT Deletes character to left of cursor. 

EVAL oxpr [LINE 

PROCEDURE 
SYMBOL [ALLll 

HELP [topic-name 

en 1 

INPUTMODEl-expd 

Utility Commands 

NAMESCOPEl-axpd 

OFFSET$OF(axprt 

PORT (port-numbed ( - expd 

V4PORJ (port-numbed[’~ expd 

SELECTOR$OF(axp/) 

WRITE [USING (tormat-item)] [expd.expd*] 
format -item - 


DEFINE TRCREG name^ trace-pt [CALL proc-name] l./race-p/[CALL proc-name]]* 

The called debug procedure must return a boolean value, as follows. BiOCk Commands 


RETURN TRUE 
RETURN FALSE 


Defining Debug Procedures, Debug Variables and Patches 


COUNT expr 
[WHILE expr 
UNTIL expr 
[command]*] 
END[COUNT] 


DEFINE PROC name [command] 


Accessing Debug Procedure Parameters 


REPEAT 
[WHILE expr 
UNTIL expr 
[command]* 
END[REPEATJ 


%expr-for-passed-parameter 

%NP 

DEFINE memory-tyep name - expr 


DO 

[command]* 

END 


DEFINE PATCH address [TIL address] [command 
NOP 1 


IF expr THEN [command] 

[ORIF expr THEN [command]]* 
(ELSE [command]] 

ENDdF] 


n Decimal number specifying the width of the output field. 

nC Move output buffer pointer to column n (first column). 

n X Skip n spaces. 

H Set display base in hexadecimal. 

T Set display base to decimal. 

Y Set display base to binary. 

Terminate the format string. 

> Terminate the format string; do not issue a <cr> or <If> until 
the next WRITE; only has meaning when within a block command 
or procedure that has more than one WRITE. 

A Terminate the format string; do not execute the WRITE until the 
next WRITE. 

'' Delimit text to be written. 


VIEW pa/hnama 


2 


3 


4 
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Intel’s Technical Publications Departments attempt to provide publications that meet the needs of all Intel 
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us correct and improve our publications. Please take a few minutes to respond. 
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